GAME PLAN 



Reboot 



No, there's nothing wrong with 
your dials. You may have been 
expecting L arry 'B rien's 
sagacious words in this space, 
and here you are reading a 
column by the guy who for- 
merly wrote Crossfire. "Just 
what the heck is going on?!" 
you might be asl<ing. 

Changes are afoot here at Game 
Developer, though nothing so radical as 
a Spindler reorg. Larry's been kicl<ed 
upstairs to editorial director, which 
means that he gets to lean back in his 
chair and watch pandemonium unfold, 
rather than having to dive into the mire 
with the rest of us. h, and he's also 
doing a lot more programming (some 
people get to have all the fun). So, 
instead, I've taken over much of the 
day-to-day housekeeping here at the 
magazine. 

Now that I've been entrusted with 
a smidge of power, my first goal is to 
work towards beefing up the number of 
articles every issue. M ore bang for your 
buck. I 'm going to try to squeeze every 
inch of this magazine to fit as many 
articles as possible into upcoming 
issues. As my previous beat was indus- 
try news and analysis, this column will 
address these issues, and the Crossfire 
column will slowly fade into the sunset. 

This issue, we examine M icrosoft's 
DirectX II SDK. If you haven't looked 
at the SD K yet, check out Robert 
H ess's article on page 24 which pro- 
vides an overview of the kit. If you've 
already started down the DirectX trail, 
however, this article may be slightly 
remedial. Don't fret. Game D ev eloper 
isn't reneging on its commitment to 
high quality, technically deep content. 
We did feel, however, that since there 
is going to be substantial coverage in 
the magazine about the current and 



future versions of D irectX SDK, it 
would make sense to have a base to 
build upon. Besides the articles in this 
issue on the W indows 95 G ame SD K, 
we'll feature three articles in the next 
issue on D IrectD raw, D irecti nput, and 
DirectBD. Though our demographics 
indicate that most of our readers work 
on games for Intel- based machines, 
we'll also add more diverse platform 
coverage. W e'll be devoting coverage to 
the upcoming M acintosh G ame SD K 
for those of you working on M ac 
games. 

Beginning this fall, we'll review 
development tools. T he first review was 
going to cover C -l-l- compilers, but, 
wouldn't you know it, C hris H ecker 
stole my thunder with his latest series 
on compilers. But look for reviews of 
various 3D animation and C -H- too Is. 

As with every byte of content that 
goes into the magazine, let us know 
what appeals to you and what doesn't. 
Want more space in the magazine 
devoted to articles, and have us post 
code on our FTP site instead of taking 
up space on the pages? r perhaps you 
want more code in the magazine and 
fewer articles. A re there any subjects that 
we haven't covered that you'd liketo read 
about? Let us know either through our 
web site, http://www.gdmag.com, or 
pick up a pen and scribble us a note. 

I've just returned from the Com- 
puter Game Developers Conference in 
Santa Clara, Calif., which was more 
packed with people than ever before- 
close to 4,000. Check out the Bit Blasts 
column, as well as our web site for 
information about new products that 
were launched at the show. ■ 



AlexD unne 
Senior Editor 
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S E Z U ! 



Exploring 
the World of 
lexture Mapping 



KEEPING CHRIS ON HIS TOES! 

Dear Editor: 

've enjoyed reading Chris Hecl^er's series on 
perspective texture mapping. His articles were 
very informative, and they were very timely 
with respect to my current project. Thanks! 

However, there are a few things in the 
February/March 1996 issue that confused me. 
First, on page 24, Figure 3, should the resulting 
exponent have the same binary exponent value 
as the higher magnitude value? In this case 
10000111 (135)? 

Also, in the first paragraph of page 24, he 
talks about subtracting "the integer representa- 
tion of our large, floating-point shift number 
from the integer representation of the number 
we just converted...." What are these numbers? 
The values to be subtracted are now; 

1 10010110 1 10000000000000000000000 
(1.1 *2^^) 

1 1 10010110 I 00000000000000000001000 
(Our8.75 lined up) 

II 100101101 11111111111111111111000 
(This gets us our -8) 

1 think this is correct! 

Kenneth Chao 
Via e-mail 



Chris Hecker replies: 

Yes, Wis is a bug, thanks for spotting it! I must 
have cut and pasted when I did the 
diagram. 

In regards to integer presentation, you have 
got one bit wrong in your result. The .1 bit gets 
borrowed from, so you end up with: 

lIlOOlOllOIOlllllllllllllllllllOOO 
l^ow, we've got a result that has our -8 embed- 



ded in the bottom, but we want to get rid of the 
top garbage. To do this, we just subtract our 
"big number" (your 1.1 * from this as an 
integer: 

11001011001111111111111111111000 

01001011010000000000000000000000 

11111111111111111111111111111000 
(Which equals -8) 

Thanks a lot! Keep up the good work! 

X MODE MARKS THE SPOT 

Dear Editor: 

Your magazine is great! I use a lot of the 
articles constantly. Especially the ones 
about breaking into the game business. It 
actually helped me land a job! 

Your X mode programming optimizations 
were great. Thanks for producing a much need- 
ed magazine. 

John Bryant 
Via e-mail 



I HAVE A TEXTURE MAPPING QUESTION! 
Dear Editor: 

've been getting Game Developer magazine 
since March 1995, and I've been especially 
following your series on texture mapping. 
Do you have any suggestions on how I could 
make a quad texture mapper, assuming that 
the points are clockwise and coplanar? Theoret- 
ically, it should not be too much of a problem, 
since the gradients across the quad are the 
same as either of the two triangles which make 
it up, or at least, should be, as far as I have 
reasoned. 

Also, how do games like Descent manage 



such fast texture mapping, while also doing 
game Al, Z buffering, and anything else that 
needs to be done? When it changes detail level, 
what is it doing? 

Stuart Doyle 
Via e-mail 



Chris Hecker replies: 

Well, general quads will work with a projective 
mapping (they won't with afflne). But, If your 
quads (or even genera! polygons) are coplanar, 
you can use the plane equations to generate the 
gradients without using the vertex texture coor- 
dinates. The math Is a bit much, but I might 
cover it in a later article. You can derive it your- 
self If you think about what you need to describe 
the plane of the texture (a vector from the origin 
to the texture origin, a U direction vector, and a 
V direction vector, all In view space). Solve foru 
and V in terms of screen space x and y (which 
are view point x/z and y/z) and you've got It 
You'll end up with rational linear equations that 
look like: 

u = (ax + by + c)/(dx + ey + f) 
u = (gx + hy + i)/(dx + ey + f) 

Also, Descent doesn't 1 buffer. The major 
speedups in real games come from novel data- 
base traversal algorithms that cull out most of 
the world before they gets to the texture map- 
per The fastest texture mapped triangles are 
the ones you didn 't draw. 



Say It! 

Please send all feedback to; Game Developer 
magazine, Feedback, 600 Harrison St., S.F., 
Calif. 91407 ortojoutlaw@mfi.com. 
Thanks! 



http://vvww.gdmag.com 
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BIT BLASTS 



Game developers unhappy about 
Microsoft's $125 Pax Romana 
toga party fee held the "First Annual 
DirectBeer lA Beta" party at a San 
J ose microbrewery. T-shirt themes 
included: "Quicl<, How many poly- 
gons am I holding up?" and "Unrelo- 
cated Crash Address: 
96DIRECT:BEER" 

Not only did M icrosoft unwittingly 
use Pax Romana (the forcible pacifi- 
cation of subject states by a larger 
power) as their theme, but their 
Game Evangelist offended even 
more developers by his "10 Reasons 
DirectX Doesn't Suck" list which 
was topped with the statement that 
it didn't matter that only .01% of 
toga attendees would be 
female. ..one of them may be a 
Playboy Bunny. Worse yet, he 
actually showed up with a well- 
endowed woman who spent the time 
dropping grapes in his mouth. 

cue, the shopping network, bought 
Sierra for a cool billion dollars. 
What did they buy? The inventory of 
old Sierra games is worth some- 
thing, but they didn't get much in the 
way of game development talent 
other than designer Roberta 
Williams. Sierra is known for its 
high turnover and regularly loses 
such assets as Lori and Cory 
Cole, cue promises hands off, so 
the takeover doesn't look like it's 
providing any management fix to 
stem defections. 

Remember Choplifter? Developer 
Danny Gorlin dropped out for four 
years for a stint of African dancing 
and drumming but has come back to 
the fold. He's working on Gravity's 
forthcoming Banzi Bug game to be 
published by Grolier. 

Wanna gossip? 
E-mail The Gossip Lady at: 

71501.3553@compuserve.com. 



On With 
"the Show 



After a few days at C G D C, I 
must decompress. I remind 
myself other humans exist. 
Peg guns, dart guns, dog tags, 
mouse pads. Nerds, Lemon- 
heads, silly string, neon neck- 
laces, and temporary tattoos 
gll seem strangely normal after 
a period of show saturation. 

COMPUT=R 
Gi.ME 

DEVEL^'PERS 
CONFERENCE™ *•• 

U nfortunately, we didn't have room 
to list all the products we wanted to 
devote space to, so check out our web 
site for a more complete scoop. H ere's a 
R eader's D igest synopsis of some products 
that were announced at or around the 
timeof theCGDC: 

• I ntel threw a big party at the C G D C 
to announce its M M X technology, a 
major multimedia enhancement to the 
Intel architecture. See http://www. 
intel.coin/pc-supp/inultiined/ininx/ to 
get M M X development information. 

• Yamaha announced plans to design 
hardware and software solutions to 
support Intel's M M X. Call (408) 
567-2300. 

• Diamond M ultimedia released Dia- 
mond E dge 3D , a multimedia acceler- 
ator with M icrosoft D irectSD support. 
Call (408) 325-7000. 

• Yamaha announced support for the 
Direct3D API and availability of 
DirectSD drivers for the R PA family 
of 3D graphics accelerators. D irect3D 
drivers are available to Yamaha's 
OEMs, content developers, and select- 
ed beta test sites. C all (408) 567-2300. 



Diane Anderson 



• 3D Labs Inc. announced that its 
Glint and Permedia 3D graphics 
accelerators will support the new 
D irect3D A PI . C all (408) 436-3455. 

• Silicon G raphics announced Silicon- 
Studio, an open-architecture for 
building digital studios. StudioCentral 
is its asset management companion, 
Firewalker is a content authoring sys- 
tem, and StudioLive is its Internet- 
based studio services network. Call 
(415)960-1980. 

• 3D fx announced System3D , a 
scaleable system based on 3Dfx's 
Obsidian graphics board for LBE 
games; it is designed for texture- 
mapped 3D arcade games. 3D fx also 
announced its Voodoo Graphics 
chipset. Call (415)934-2400. 

• Apple, Netscape, and Silicon Graph- 
ics recently agreed to cooperate on 3D 
graphics for the I nternet. T he three 
companies plan to develop a new 
binary file format for M oving W orlds 
(a leading proposal for VRM L 2.0) 
based on Apple's 3D metafile format 
(3D M F) technology. M oving W orlds 
is an open, cross- platform specifica- 
tion for dynamic 3D environments on 
the I nternet, which enables higher 
compression, file streaming, and faster 
parsing of 3D objects and virtual 
worlds across the I nternet. 

• A pple announced G ame Sprockets, 
their new G ame SD K . C heck out 
http://www.dev.apple.coin/gaines. 



For full descriptions, pricing, and contact 
information on these and other products, 
please surf to the new and improved 
Game Developer web site located at 
http://www.gdmag.com. 
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BEHIND THE SCREEN 



PowerPC 
Compile 
II N 



ot So Hot 



believe it was Theodore Roosevelt 
who first called the presidency of the 
United States a "bully pulpit," which 
is a catchy way of saying that the 
president can rant on a subject, peo- 
ple will actually listen, and maybe 
those people will even do something 
about whatever the topic of the rant 
happens to be. M agazine columns can be 
bully pulpits as well, and, while a comput- 
er magazine column is clearly not a pulpit 
on the same level as the W hite H ouse, I 
don't expect to hear Bill Clinton taking 
compiler vendors to task about lame opti- 
mization quality in the next State of the 
Union Address, so I might as well do it 
myself. 

Review Problems 

This article started out as a comparative 
review of compiler optimizations, but the 
more I learned about the various compil- 
ers and how they did or did not optimize. 



the more the article turned into an explo- 
ration of how we as programmers have to 
help the compilers do a good job with our 
code. So while I 'm still going to talk 
about five compilers and give comparison 
charts like a normal review, I'm actually 
going to concentrate on how our source 
code changes affect the assembly the 
compiler generates 

M ost other compiler reviews focus 
on the compiler's integrated development 
environment, on the fancy editor with 
color syntax highlighting that doesn't even 
let you write a simple macro, on the 
debugger's silly ToolTip windows (that 
pop up over variable names with their val- 
ues if you hold your mouse there forever), 
and on the compiler supplied class library 
that violates just about every precept of 
good object-oriented design in C-H-and is 
bloated and slow to boot. W ow! As you 
can see, I 'm no fan of compiler reviews— I 
believe most are written by either nonpro- 



Table 1. Tran 

Compiler 


sform Cyc 

Listing 
1 


le Counts 

Listing 
2 


KAPed 1 
(not shown) 


Listing 
4 


Listing 
5 


Listing 
6 


CodeWarrior 


40.7 


50.5 


50.9 


34.3 


29.7 


19.6 


Symantec C-n- 


76.6 


94.9 


82.8 


50.9 


31.9 

1 


25.7 


Motorola C-i-i- 


34.5 


47.4 


39.5 


33.2 


30.8 

1 


20.6 


Apple's MrCpp 


52.0 


65.0 


56.2 


36.1 


28.8 

1 


19.5 


Microsoft VC-i-i- 


41.6 


49.3 


42.8 


31.9 


21.9 

1 


22.7 



grammersor nonproduction programmers 
writing toy programs. Compilers them- 
selves are written for those reviewers, and 
so we end up with the current mess, 
where compiler vendors focus on silly new 
features to please silly reviewers instead of 
focusing on things that actually help pro- 
duction programmers do their jobs well. 

W hen I evaluate a compiler I look 
for two things: C-H- compliance and code 
optimization. The former is basically a 
lost cause at this point because the C -H- 
draft standard is still a moving target and 
there's no solid conformance suite. I pray 
this will change soon. By contrast, com- 
piler writers have had years to work on 
compiler optimizations, and not much 
has changed since the early days. 

By focusing on optimizations, we'll 
not only learn which compilers optimize 
the best, we'll also learn what we can do 
to help a compiler do its best with our 
code. This time, we'll be covering compil- 
ers for the PowerPC chip on the M acin- 
tosh, and next time we'll cover the I ntel 
x86. Even if you don't program for the 
PowerPC, reading this will help you learn 
a lot about compilers and how they opti- 
mize, and that knowledge will carry across 
to whatever CPU you care to program. 

The compilers we'll cover this issue 
are: M etrowerks C odeW arrior 8, Syman- 
tec C-H- 8, version 1.0f3e2 of Apple's 
M rC pp compiler (which is included with 
the Symantec compiler), M otorola's 2.1.1 
PowerPC C compiler, and the 
M icrosoft Visual C-H-for M acintosh 4.0 
cross compiler. 

The Test Code 

W e'll use a simple inner product of a 
three- by- three matrix and a three ele- 
ment column vector to evaluate each 
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compiler's optimization quality. Obvi- 
ously, a single function is not going to 
tell the whole optimization story, but it 
should give us an idea of what sorts of 
optimizations we can expect from today's 
compilers. 

Listing 1 shows the function Trans- 
formVectors. I made it transform an array 
of vectors so the compilers would have to 
worl< a bit harder, but, even so, the code is 
trivial. I used 1,000 calls to this function 
with 500 transforms on each call to gather 
timing information. The first column of 
data in Table 1 shows the approximate 
cycle counts for each product measured 
with the M acOS call Microseconds for the 
various compilers on my Power C omput- 
ing 604. 1 turned on all the optimizations 
I could find on each compiler to gather 
this data. I made sure my test program 
was producing correct results on every 
compiler by making the source vectors 
eigenvectors of the transform matrix and 
checl<ing to see if the transformed vector 
was the same as the source— it's always a 



Listing 1. The Test Function 



good idea to mal<e sure neither you nor 
the compiler has introduced any bugs 
whileoptimizing. 

Anti-Alias 

If you've lool<ed ahead at the other 
results in Table 1 and the other listings, 
you're probably wondering what the sec- 
ond column of data means, and why 
L isting 2 is almost identical to L isting 1. 
Even though you and I know we 
wouldn't call IransforinVectors from L ist- 
ing 1 with the source or destination 
pointing to the same vector, or, worse 
yet, with the destination pointing into 
the middle of the matrix somewhere, the 
compiler doesn't know this, so it can't 
assume we didn't do something silly. 
W hen a variable points to another live 
variable in the function, it's called 
"pointer aliasing," and when the compil- 
er sees a write through a pointer, it needs 
to assume that the data could have land- 
ed anywhere, including into variables it's 
already loaded into registers. T his means 



i/oid TransformVectorsC float *pDestVectors, 

float const {♦pHatrix)[3], float const ♦pSourceVectors, 
int NumberOfVectors ) 



{ 



int Counter, i, j; 

for(Counter = 0;Counter < NuinberOfVectors;Counter++) { 
for(i = 0;i < 3;i++) { 

float Value = 0; 
for(j = 0;j < 3;j++) { 

Value += p[1atrix[i][j] * pSourceVectors[j]; 

} 

*pDestVectors++ = Value; 

} 

pSourceVectors += 3; 

} 



Chris Hecker 

Compilers, iat are 
they good for? Chris 
Hecker steps to the 
bully pulpit to rant 
about the state of 
current PowerPC 
compilers, Sadly, these 
days, most compilers 
need a lot of help 
optimizing code, 
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Listing 2. Tlie Non-Aliasing Test Function 



void TransforiiiVectors2{ float *pDestVectors, 

float const {*pHatrix)[3], float const *pSourceVectors, 
int NumberOfVectors ) 

{ 

int Counter, i, j; 

for(Counter = 0;Counter < NuinberOfVectors;Counter++) { 
float aTeiiip[3]; 
for(i = 0;i < 3;i++) { 

float Value = 0; 
for(j = 0;j < 3;j++) { 

Value += p[1atrix[i][j] ♦ pSourceVectors[j]; 

} 

aTeiiip[i] = Value; 

} 

pSourceVectors += 3; 
for(i = 0;i < 3;i++) { 

*pDestVectors++ = aTeiiip[i] ; 

} 

} 

} 



the optimizer has to continually reload 
variables into registers in case we're alias- 
ing parameters, so I wrote Transform- 
Vectors2 in L isting 2 to give the compil- 
ers some help. Since aTemp is defined 
local to our function, the compiler 
knows it can't be aliased, so writes to 
aTemp shouldn't cause spurious register 
reloads. 

W ell, at least that's what I thought, 
anyway. As you can see from the tim- 
ings, all the compilers got slower because 



not only did they still reload all the reg- 
isters, they also naively implemented the 
copy loop at the end of L isting 2! 

Let's look at the code generated by 
the winner of this round, the M otorola 
C compiler. L isting 3 shows the 
PowerPC assembly language generated 
for TransforinVectors2, OUr supposedly 

non-aliased function. Despite some odd 
ways of moving values into registers, this 
code is a pretty straightforward transla- 
tion of our source into assembly language. 



which is disappointing. For example, the 
compiler doesn't bother to load the source 
vector into registers outside the loop, even 
though it's used three times and cannot 
be aliased because of our temporary 
results array. Also, instead of leaving the 
temporary results in registers, it actually 
copies them out to the stack and then 
copies the stack to the destination. 

It even increments the destination 
pointer in the loop with three discrete 
instructions instead of using offsets and 
doing one addition at the end, or even 
using the PowerPC 's autoincrement 
instructions. The M otorola compiler also 
produced the fastest code for L isting 1, 
and the difference between the timings 
for Listings 1 and 2 can be attributed to 
the naive compilation of the temporary 
copy loop at the end of Listing 2 (even 
though the temporary loop was supposed 
to help by eliminating the possibility of 
aliasing). Overall, not a great showing, 
even by our winner in this round. C learly, 
the compilers need more help. 

Busta KAP 

T he M otorola compiler ships with an 
interesting tool, called the Kuck and 
Associates Preprocessor for C (KAP). 
Basically, KAP compiles your C code (it 
doesn't support C-l-f-), optimizes it, and 
then generates C code as its output 



Listing 3. IVIotorola C++ Assembly for Listing 2 


TransforinVectors2_ 


.FPfPA3.CfPCfi.b: 






stfsx 


f2,r8,r7 


♦(stack + r7) = f2 


cmpi 


0x7,0x0, r6,0 


compare count to 




add! 


r7,r7,4 


r7 next float 


addi 


rll,rO,0 


Counter = rll = 




be 


0xl0,0x0,L..9 


branch if (--ctr) 


be 


0x4,0xld,L..ll 


bail out if count = 




Ifs 


fl,0(r8) 


fl = stack [0] 


addi 


r8,sp,24 


allocate some stack 




Ifs 


f2,4(r8) 


f2 = stack [1] 


L..8: ori 


r9,r4,0x0 


r9 = pHatrix 




Ifs 


f3,8(r8) 


f3 = stack [2] 


addi 


rlO,rO,0 


rlO = 




stfs 


fl,0(r3) 


pDest[0] = fl 


ori 


r7,rl0,0x0 


r7 = 




add! 


r3,r3,4 


pDest++ 


subfic 


rl0,rl0,3 


rlO = 3 




addi 


rll, rll, 1 


Counter++ 


mtctr 


rlO 


ctr = 3 




stfs 


f2,0(r3) 


pDest[l] = f2 


L..9: Ifs 


fl,0(r9) 


fl = pHatrix[Q] 




addi 


r3,r3,4 


pDest++ 


Ifs 


f2,0(r5) 


f2 = pSource[Q] 




cmp 


0x7, 0x0, rll, r6 


flags = Counter < 


Its 


f3,4(r9) 


f3 = pnatrix[l] 




NumVecs 






Ifs 


f4,4(r5) 


f4 = pSource[l] 




addi 


r5,r5,12 


pSource += 3 


fmuls 


fl,fl,f2 


fl = fl ♦ f2 




stfs 


f3,0(r3) 


pDest[2] = f3 


Ifs 


f2,8(r9) 


f2 = pHatrix[2] 




addi 


r3,r3,4 


pDest++ 


Ifs 


f5,8(r5) 


f5 = pSource[2] 




be 


0xc,0xlc,L..8 


branch if (Counter < 


fmadds 


f3,f3,f4,fl 


f3 = f3 ♦ f4 + fl 




NumVecs) 






addi 


r9,r9,12 


pl1atrix->next row 




L..11: addi 


sp,sp,48 


clear stack 


fmadds 


f2,f2,f5,f3 


f2 = f2 ♦ f5 + f3 




belr 


0x14,0x0 


return 
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Listing 4. Tlie KAPed Listing 2 


void TransfoririVectors2( float *pOestVectors, 

const float (*pl1atrix)[3], const float ♦pSourceVectors, 
int NumberOfVectors ) 

{ 

int Counter, i, j; 
float aTeirip[3]; 

float Value, .Krrl, .Krr2, .Krr4, .Krr5; 
long .KiLl, .KiL2; 

for ( Counter = 0; Counter<Nu[nberOfVectors; Counter++ ) { 
.Krrl = O.OF; .Krr2 = O.OF; Value = O.OF; 




.Kill = Counter * 3; 

.Krrl += pBatrix[0][0] * pSourceVectors [.Kill]; 
.Krr^ +- pHatrix LIJ LuJ * poourcevectorsL.KiilJ; 
Value += pBatrix[2][0] * pSourceVectors [.Kill]; 
.Krrl += pBatrix[0][l] * pSourceVectors [.KiLl+l]; 
.Krr2 += pNatrix[l][l] * pSourceVectors [.KiLl+l]; 
Value += pHatrix[2][l] * pSourceVectors [.KiLl+l]; 
if (1) { 

.Krrl += pl1atrix[0][2] * pSourceVectors[.KiLl+2]; 
.Krr2 += pl1atrix[l][2] * pSourceVectors[.KiLl+2]; 



instead of assembly language. W hen I 
first got the M otorola compiler, I figured 
my test would be so simple that there was 
no way KAP could help out, but after 
lool<ing at the results we just discussed, I 
figured anything was worth a try. Listing 
4 shows the output of running L isting 2 
through KAP (they call the processed 
code KAPed). If you've never seen 
machine-generated C code, don't be sur- 
prised by stuff like the "if (l)" block- 
compilers output weird stuff like that for 
bizarre reasons. H owever, you should be 
surprised at how poor the code is. It 
unrolls the loop, which is fine, but why 
does it go to the trouble of putting the 
temporaries in aTemp and then looping 
over aTemp to copy them into the destina- 
tion? M ore absurd yet is that something 
as mundane as unrolling a loop in this 
simple function actually helped the com- 
pilers produce faster code. 

You can see the timing results in 
Table 1. The KAPed Listing 1 is not 
even worthy of print, and as you can see 
the compilers all got slower on that ver- 
sion. The KAPed Listing 2 (shown in 
L isting 4) actually made a positive differ- 
ence, even on the best compilers, and it 
made a huge difference on Symantec. 
Even so, if you thought it was bad that 
KA P generated the redundant loop at the 
end of Listing 4, it's even worse that every 
compiler generated actual assembly lan- 
guage code for that loop! The worst 
offender is clearly Symantec. Symantec 
ships a prerelease version of Apple's 
M rCpp compiler with their package, so 
it's unclear if I should even review 
Symantec on their optimization quality 
because I think they expect you to use 
|vi rC pp if you care about run- time speed. 
H owever, M rC pp and Symantec's main- 
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Listing 4. Continued from p. 16 



pHatrix[2][2] * pSourceVectorsLKiil+2]; 

Krr2; aTemp[2] = Value; 



Value 

} 

aTempM = _Krrl; aTeirip[l] = 
_KiL2 = Counter * 3; 
for ( i = 0; i<=2; i++ ) { 

.Krr5 = aTeirip[i]; .Krr4 = .Krr5; 

pDest»ectors[.KiL2+i] = .Krr4; 

} 



} 

pSourceVectors + 
pOestVectors += 



■ NumberOf Vectors * 3; 
NuiiiberOfVectors ♦ 3; 



line compiler are not C ++ feature- equiva- 
lent, so I 'm not sure how they can expect 
you to freely exchange them. 

A Helping Hand 

A t this point, it was clear that the compil- 
ers by themselves— and even with the 
help of KAP, for what it's worth— were 
not going to be able to produce reason- 
able code for these functions, so I had to 



step in and give them 
a hand. I lool<ed at 
what kind of 
improvement KAP 
got from using what } 
I had assumed were } 
brain- dead rewrites 
(I can't even bring myself to call them 
optimizations), and I decided to hand 
code the Transform functions to see what 



Listing 5. Hand-optimized Listing 1 



void TransformVectorsC float *pDestVectors, 

const float (*pMatrix)[3], const float tpSourceVectors, 
int NumberOfVectors ) 

{ 

int Counter; 

float ValueO, Valuel, Value2; 

for { Counter = 0; Counter<NumberOfVectors; Counter++ ) { 
ValueO = pMatrix[0][0] ♦ pSourceVectors[0]; 
ValueO += pl1atrix[0][l] * pSource«ectors[l]; 
ValueO += pl1atrix[0][2] ♦ pSourceVectors[2]; 
*pDestVectors++ = ValueO; 
Valuel = pMatrix[l][0] * pSourceVectors [0]; 
Valuel += pl1atrix[l][l] * pSourceVectors[l]; 
Valuel += pl1atrix[l][2] * pSourceVectors[2]; 
*pDestVectors++ = Valuel; 
Value2 = pHatrix [2] [0] * pSourceVectors [0]; 
Value2 += pl1atrix[2][l] ♦ pSourceVectors[l]; 
Value2 += pl1atrix[2][2] ♦ pSourceVectors [2]; 
*pDestVectors++ = Value2; 
pSourceVectors += 3; 



would come out. L istings 5 and 6 contain 
the hand-optimized versions of L istings 1 
and 2, respectively. You can see from the 
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Listing 6. Hand-optimized Listing 2 



void TransforinVectors2( float *pDestVectors, 

const float {♦pHatrix)[3], const float *pSourceVectors, 
int NumberOfVectors ) 



{ 



int Counter; 

float Value, Jrrl, .Krr2; 

for ( Counter = 0; Counter<NuinberOfVectors; Counter*' 
_Krrl = pnatrix[0][0] + pSourceVectors[0]; 
.Krr2 = pnatrix[l][0] * pSourceVectors[0]; 
Value = pnatrix[2][0] * pSourceVectors[0]; 
Jrrl += p[1atrix[0][l] * pSourceVectors[l]; 



.Krr2 += 
Value += 
.Krrl += 
.Krr2 += 
Value += 
♦pDestVectors++ 
*pDestVectors++ 
*pDestVectors++ 
pSourceVectors ■ 



p[1atrix[l][l] ♦ 
p[1atrix[2][l] * 
p[1atrix[0][2] * 
p[1atrix[l][2] * 
p[1atrix[2][2] * 
.Krrl; 
.Krr2; 
Value; 
3; 



pSourceVectors[l] 
pSourceVectors[l] 
pSourceVectors[2] 
pSourceVectors[2] 
pSourceVectors[2] 



timing results in the 
last two columns of 
Table 1 that it made 
a big difference on all 
the compilers. 

Why did it 
make such a big dif- 
ference? I have no 
idea, and the only 
explanation I can 
come up with is that 
you need to hold 
your compiler's hand 
on any piece of code 
you care about. T he 
changes I made for 
L istings 5 and 6 are 
very obvious (to a 
human, if not a com- 
piler). I 'm basically 
just stating explicitly 
where variables are 
accessed, where pos- 
sible aliasing can 



occur, and which variables are constant 
throughout a loop iteration. These are all 
things the compiler is supposed to do for 
us, so we can worl< on more important 
stuff, lil<e design and algorithms, or 
assembly language code for our most 
inner loops. W e're supposed to trust the 
compiler will do a respectable job, with- 
out having to optimize every line of our 
code (an impossible task for all but the 
smallest programs). 

N ow, if you're like me, you've been 
waiting to say something about all this 
loop unrolling for a while now. You're 
waiting to say that you don't actually 
want the compiler to unroll loops all over 
the place, because that makes your code 
bigger and probably slower. H ah! I was 
waiting for you to say that, because the 
most amazing thing of all about this test 
is that a couple of the compilers pro- 
duced code for Listing 6 that is smaller 
than the code for the original non- 
unrolled Listing 2. Listing 7 shows the 
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C odeW arrior version of L isting 6; it's at 
least 6 instructions smaller than any of 
the compiled versions of Listing 2, and 
about two to five times as fast. M otorola 
produced similar code. (M rCpp decided 
now was the time to unroll the entire 
function, which tripled the size of the 
code for absolutely no performance 
increase.) Don't for a minute thinl< this 
is a compliment for C odeW arrior or 
M otorola, it's really a damning insult to 
all the compilers: on maximum opti- 
mizations they didn't find the smaller 
and faster version of a basic function lil<e 
a matrix transform. H eck, just by inspec- 
tion I can see how to save a couple more 
instructions in Listing 7. And people 
actually say that writing assembly lan- 
guage is a dying art. 

You Lose Some 

If this was a normal compiler review, it 
would be time to picl< a winner, but, 
instead, it's time to point out that you and 



I are the losers in this situation. Pundits 
have been saying that assembly language 
is dead— especially on RISC chips lil<e 
the PowerPC — and it should be eminent- 
ly clear from the listings in this article 
that those people have no clue what 
they're tall<ing about. Even a beginning 
assembly language programmer could 
produce better code than any of the com- 
pilers for L istings 1 and 2, and this is 
simple code. W hileyou might not choose 
to write your code in assembly language, 
you end up with C code that lool<s like 
assembly language if you want respectable 
performance, like Listings 5 and 6. 

If I had to choose a winner, I'd pick 
the M otorola C -H- compiler, because it 
seems like the least incompetent optimiz- 
er of the bunch. The M icrosoft compiler 
showed some promising aggressiveness by 
loading the entire matrix into registers 
once at the top of the loop for its version 
of Listings 5 and 6. M icrosoft has an 
option I turned on that tells the compiler 



there's no pointer aliasing that allowed 
them to perform this optimization, but 
they didn't take advantage of the assump- 
tion anywhere else that I could see. G iven 
this optimization, I'm not sure why their 
version of L isting 6 wasn't faster than the 
others... it may have been a pipelining 
issue, or the loop might have been cache 
bound. As soon as I learn a bit more 
about the subtleties of the PowerPC 604, 
I 'II get back to you on this one 

I n the next issue, I 'II quickly cover a 
bunch of Intel x86 compilers, but we will 
still have room to talk about some opti- 
mization programming techniques of our 
own, because the compilers clearly aren't 
going to do it for us. 

This Just In: I was keeping M ike 
Phillip at M otorola's compiler group 
posted on my results, and he just got 
back to me with a command line switch 
for KAP that will assume there's no 
aliasing. W hen you turn it on, KA P pro- 
duces something resembling Listing 6, 
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Listing 7. CodeWarrior version of Listing 6 



Transfo™«ectors2..FPfP*3.CfPCfi 



mr 


rO,r6 ; rO = NumVecs 


aiipui 


r6,0 ; flags = NumVecs == 


mtctr 


rO ; ctr = NumVecs 


blelr 


; bail if(NumVects == 0) 


LI: Ifs 


fpl,0(r4) ; fpl = pHatrix[0][0] 


Ifs 


fp3,0(r5) ; fp3 = pSource[0] 


Ifs 


fp0,12(r4) ; fpO = pHatrix [1] [0] 


Ifs 


fp2,24(r4) ; fp2 = pNatrix [2] [0] 


fmuls 


fp7,fpl,fp3; fp7 = fpl * fp3 


Ifs 


fpl,4(r4) ; fpl = p«atrix[0][l] 


Ifs 


fp5,4(r5) ; fp5 = pSource[l] 


fmuls 


fp8,fpO,fp3; fp8 = fpO * fp3 


fmuls 


fp6,fp2,fp3; fp6 = fp2 * fp3 


Ifs 


fp0,16(r4) ; fpO = pHatrix [1] [1] 


Ifs 


fp4,28(r4) ; fp4 = pNatrix [2] [i] 


Ifs 


fp2,8(r5) ; fp2 = pSource[2] 


fmadds 


fp7,fpl,fp5,fp7 




; fp7 = fpl ♦ fp5 + fp7 


add! 


r5,r5,12 ; pSource += 3 


Ifs 


fp3,8(r4) ; fp3 = pNatrix[0][2] 


fmadds 


fp8,fpO,fp5,fp8 




; fp8 = fpO ♦ fp5 + fp8 


Ifs 


fpl,20(r4); fpl = pHatrix[l][2] 


fmadds 


fp6,fp4,fp5,fp6 




; fp6 = fp4 * fp5 + fp6 


Ifs 


fp0,32(r4); fpO = pHatrix[2][2] 


fmadds 


fp7,fp3,fp2,fp7 




; fp7 = fp3 * fp2 + fp7 


fmadds 


fp8,fpl,fp2,fp8 




; fp8 = fpl * fp2 + fp8 


fmadds 


fp6,fpO,fp2,fp6 




; fp6 = fpO * fp2 + fp6 


stfs 


fp7,0(r3) ; pDest[0] = fp7 


stfsu 


fp8,4(r3) 




; pDest[l] = fp8, pDest++ 


stfsu 


fp6,4(r3) 




; pDest[l] = fp6, pDest+<- 


add! 


r3,r3,4 ; pDest++ 


bdnz 


LI ; branch if (~ctr) 


blr 


; return 



SO all the compilers do well. H owever, 
not to be out- done, I decided to take this 
no-aliasing assumption to the limit and 
explicitly load the matrix into tempo- 
raries (much like the M icrosoft compiler 
tried to do). The result: another 25% 
speedup, with times around 15 cycles, 
for something the compiler could have 
done itself. T he compilers lose again. ■ 

Chris H ed<a' tries to live an optimized 
life, but he does about as good of a job on his 
own life as the current aop of ODmpilersdoes 
on hisaxJe Contact him at gdmag@mfi.Q3m. 
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APIS 



I n-troduction 
to the DirectX 

II APIs 



Once upon a time, developing 
□ames for the PC wasn't easy, 
bos allowed game develop- 
Irs access to low- level systems 
linctions, enabling good per- 
prmance, but few standards 
were in place to support the 
wide variety of hardware 
found in PCs. Developing under Win- 
dows 3.x wasn't any better, due to per- 
formance bottlenecl<s. H owever, with 
last year's release of W indows 95, a door 
has been opened to the development of 
high-performance, Windows-based 
games. And the l<ey to that door is 
M icrosoft's Game Software Develop- 
ment Kit (SD K). 

T he primary goal of the G ame 
SD K is to mal<e performance on W in- 



dows rival or exceed performance on 
DOS- based platforms and console sys- 
tems and to provide a robust, standard- 
ized, and well-documented platform for 
game developers. A high-performance 
W indows- based game installs success- 
fully and tal<es advantage of hardware 
accelerator cards, W indows hardware 
and software standards (such as Plug- 
and-Play), and the W indows communi- 
cations services. 

T he G ame SD K, which you can 
find in the M icrosoft Developer Net- 
work (M SD N ) L evel 1 1 , provides a con- 
sistent interface for hardware manufac- 
turers and game developers. It reduces 
the complexity of installing and config- 
uring games and uses a computer's 
hardware to the best advantage. DOS- 




based games can still take advantage of 
the hardware cards available to the 
Game SDK developer; however, DOS- 
based game developers must conform to 
varying implementations of cards— 
which complicates the installation. 

New Standards for 
Hardware Vendors 

The Game SDK provides portable 
access to the features of DOS today, 
keeps a high level of performance, and 
removes obstacles to hardware innova- 
tion. T he G ame SD K tries to provide 
guidelines for hardware companies 
based on feedback from game develop- 
ers and independent hardware vendors 
(IH Vs). Therefore, the Game SDK 
components often provide specifications 
for hardware accelerator features that do 
not yet exist. I n many cases, these speci- 
fications are emulated in software. In 
other cases, the capabilities of the hard- 
ware are polled first, and the feature is 
bypassed if it is not supported by the 
hardware. 

T he G ame SD K supports a num- 
ber of video hardware features that have 
already come out (or will be released in 
the near future). T hese include: 

• Overlays 

• Page flipping 

• Sprite engines 

• Stretching with interpolation 

• Alpha blending 

• Z buffer- aware bit- block transfers. 

Overlays will be supported so that 
page flipping will also be enabled within 
a window using graphic device interface 
(GDI). Page flipping is the double- 
buffer scheme used to display frames on 
the entire screen. Sprite engines are 
used to make overlaying sprites easier. 
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stretching with interpolation is stretch- 
ing a smaller frame to fit the entire 
screen; it can be an efficient way to con- 
serve video RAM . Alpha blending is 
used to mix colors at the hardware pixel 
level. Three-dimensional (3D) accelera- 
tors with perspective- correct textures 
will allow textures to be displayed on a 
3D surface; for example, hallways in a 
castle generated by 3D software can be 
textured with a bricl< wall bitmap that 
maintains the correct perspective. As 
3D games generally need at least 2ivi B 
of video memory, the Game SDK sup- 
ports this. A compression standard to 
put more data into display memory will 
include transparency compression, will 
be usable for textures, and will be very 
fast when implemented in software as 
well as hardware. 

The audio hardware features that 
the G ame SD K supports or will soon 
include are the following: 

• 3D audio enhancers that provide a 
spatial placement for different 
sounds (particularly effective with 
headphones) 

• nboard memory for audio boards 

• Audio-video combination boards that 
share onboard memory. 

I n addition, video playback will see 
the benefit from Game SDK-compati- 
ble hardware. Future releases of the 
Game SDK will support hardware- 
accelerated decompression of YUV 
video. 

Taking It Apart 

T he G ame SD K is made of several 
interfaces that target performance 
issues of game programming under 
W indows 95. T he following are API s: 



• T he D irectD raw A PI accelerates 
hardware and software animation 
techniques by providing direct access 
to bitmaps in offscreen video memory 
as well as fast access to the bit-block 
transferring and buffer-flipping capa- 
bilities of the hardware. 

• The D irectSound API enables hard- 
ware and software sound mixing and 
playback. 

• The DirectPlay API lets you develop 
games for play over a modem line or 
a network. 

• TheDirect3D API provides direct 
low- level access to 3D hardware, 
allowing D irectD raw surfaces to be 
used both as 3D rendering targets 
and as source texture maps. 

• T he D irecti nput A PI provides joy- 
stick input capabilities that are 
scaleable to future W indows hard- 
wareinputAPI and drivers. 

• The A utoP lay feature lets your CD- 
ROM run an installation program or 
the game itself immediately upon 
insertion of the disc. 

Note: D irecti nput and AutoPlay 
exist in the M icrosoft Win32 API and 
aren't unique to theG ameSD K. 

DirectDraw 

The biggest gain in performance in the 
G ame SD K comes from the D irectD raw 
services, which are a combination of four 
COM interfaces: IDirectDrau, IDirect- 
DrawSurface, IDirectDrauPalette, and IDi- 
rectDrauOipper. A DirectDrau object, cre- 
ated using the function DirectDrauCreate, 
represents the video display card. ne of 
the object's member functions, IDirect- 
Draw: :CreateSurface, creates the primary 
DirectDrauSurface object, which repre- 
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Rober-t Hess 

Through the use of 
DirectXAPl5,youcan 
develop with a 
consistent interface; 
yourWndows 
games can 
outperform their 
DOS- based ancestors 
and automatically 
take advantage of 
hardware 
acceleration where 
it's available, 
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sents the video display memory being 
viewed on the monitor. From the prima- 
ry surface, offscreen surfaces can be cre- 
ated in a linl<ed-list fashion. 

I n the most common case, a bacl<- 
buffer surface is created (in addition to 
the primary surface) and is used to 
exchange images with the primary sur- 
face. W hile the screen is busy displaying 
the lines of the image in the primary 
surface, the back- buffer surface frame is 
composed by transferring a series of off- 
screen bitmaps stored on other Direct- 
DrauSurface objects in video RAM . Call 
the DirectDrauSurface: :Flip member 
function to display the recently com- 
posed frame, which sets a register so 
that the exchange occurs when the 
screen performs a vertical retrace. This 
is asynchronous, so the game can con- 
tinue processing after calling DirectDrau- 
Surface:: Flip. (The bacl< buffer is auto- 
matically write- blocked after calling 
DirectDrauSurface: :Flip until the 
exchange occurs.) After the exchange 
occurs, the game continues to compose 
the next frame in the back buffer, calls 
DirectDrauSurface: :Flip, and SO on. 

DirectDraw improves performance 
over the W indows 3.1 GDI model, 
which does not have direct access to 
bitmaps in video memory. Therefore, 
bit- block transfers always occur in host 
RAM and are then transferred to video 
display memory. Using DirectDraw, all 
processing is done on the card whenever 
possible. DirectDraw improves perfor- 
mance over the W indows 95 and W in- 
dows N T G D I model that uses the Cre- 
ateOiBSection function to enable hard- 
ware processing. 

T he third type of D IrectD raw 
object is DirectDrauPalette. Because the 
physical display palette is usually main- 
tained in video hardware, an object rep- 
resents and manipulates it. T he iDirect- 
DrauPalette interface implements 
palettes in hardware. These bypass 
W indows palettes and are therefore only 
available when a game has exclusive 
access to the video hardware. Direct- 
DrauPalette objects are also created from 
DirectDrau objects. 

T he fourth type of D IrectD raw 
object is the DirectDrauClipper. Direct- 



D raw manages clipped regions of dis- 
play memory by using these objects. A 
bitmap is transferred to a surface using a 
transparent bit- block transfer, and a cer- 
tain color (or range of colors) in the 
bitmap is defined as transparent. Color 
keying achieves a transparent bit- block 
transfer. Source color keying defines 
which color or color range on the 
bitmap is transparent (and therefore not 
copied during a transfer operation). 
Destination color keying defines which 
color or color range on the surface will 
be covered by pixels of that color or 
color range in the source bitmap. 

F inally, D irectD raw supports over- 
lays in hardware and by software emula- 
tion. Overlays are an easy means of 
implementing sprites and managing 
multiple layers of animation. Any 
DirectDrauSurface object can be created 
as an overlay, and any overlay has all of 
the capabilities of any other surface- 
plus extra capabilities associated only 
with overlays. These capabilities require 
extra display memory, and, if there are 
no overlays in display memory, the over- 
lay surfaces can exist in host memory. 

Color keying works the same for 
overlays as for transparent bit- block 
transfers. The Z order of the overlay 
automatically handles the occlusion and 
transparency manipulations between 
overlays. 

You can find source code for a 
D irectD raw application on the G ame 
Developer web site. The bulk of this 
code comes from the generic sample 
sources I wrote for the W in32 SDK. I 
made minor additions and modifications 
to enable this application to utilize the 
D irectD raw features of the new D irectX 
A PI s for W indows. This code is not 
meant to illustrate a great DirectDraw 
application, but simply to show you how 
easily DirectDraw can be added to a 
Windows application model. There are 
several sample applications that come 
with the Game SDK that better illus- 
trate some of the more advanced fea- 
tures and capabilities of DirectX. 

DirectSound 

Game programming requires efficient 
and dynamic sound production. 



M icrosoft provides two methods for 
achieving this: M I D I streams and 
D irectSound. MIDI streams are actually 
part of the W indows 95 multimedia 
API. They provide the ability to time- 
stamp MIDI messages and send a buffer 
of these messages to the system, which 
can then efficiently integrate them with 
its processes. M ore information about 
MIDI streams can be found in the 
W in32 SD K documentation. 

D irectSound is built on the C M - 
based interfaces iDirectSound and iDi- 
rectSoundBuffer, and it's extensible to 
other interfaces. DirectSound imple- 
ments a new model for playing back 
digitally recorded sound samples and 
mixing different sample sources togeth- 
er. As with other object classes in the 
G ame SD K , you should use the hard- 
ware to its greatest advantage whenever 
possible and emulate a hardware feature 
in the software when the feature is not 
present in hardware. You can query 
hardware capabilities at run-time to 
determine the best solution for any 
given personal computer configuration. 

The DirectSound object represents 
the sound card and its various attributes. 
Using a DirectSound object, you create 
the DirectSoundBuffer object, which rep- 
resents a buffer containing sound data. 
Several DirectSoundBuffer objects can 
exist and be mixed together into the pri- 
mary DirectSoundBuffer object. Direct- 
Sound buffers are used to start, stop, 
and pause sound playback and to set 
attributes such as frequency, format, and 
so on. Depending on the card type, 
DirectSound buffers can exist in hard- 
ware as onboard RAM , wave table 
memory, a D M A channel, or a virtual 
buffer (for an I/O, port- based audio 
card). W here there is no hardware 
implementation of a DirectSound 
buffer, it is emulated in host system 
memory. 

The primary buffer is generally 
used to mix sound from secondary 
buffers but can be accessed directly for 
custom mixing or other specialized 
activities. (Use caution in locking the 
primary buffer, because this blocks all 
access to the sound hardware from other 
sources.) Secondary buffers can store 
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common sounds that are played 
throughout a game. A sound stored in a 
secondary buffer can be played as a sin- 
gle event or as a looping sound that 
plays repeatedly. You can use secondary 
buffers to play sounds that are larger 
than available sound buffer memory. 
W hen used to play a sound larger than 
the buffer, the secondary buffer is a 
queue that stores the portions of the 
sound about to be played. 

DirectPlay 

One of the best features of PCs as a 
game platform is their easy access to 
communication services. DirectPlay 
capitalizes on this and allows multiple 
players to interact during game play 
through standard modems, network 
connections, or online services. 

The iDirectPlay interface contains 
methods providing capabilities such as 
creating and destroying players, adding 
players to and deleting players from 
groups, sending messages to players, 
inviting players to participate in a game, 
and so on. 

DirectPlay is composed of the 
interface to the game, as defined by the 
IDirectPlay interface and the D irectPlay 
server. DirectPlay servers are provided 
by M icrosoft for modems and networlcs, 
as well as by third parties. W hen using a 
supported server, D irectPlay- enabled 
games can bypass connectivity and com- 
munication overhead details. 

Direct3D 

D IrectBD is the newest addition to 
M icrosoft's D irectX family of API s and 
provides developers with an API and 
system services for real-time 3D graph- 
ics. DirectBD is based on the Reality 
Lab technology acquired by M icrosoft 
in 1995 when they purchased Render- 
M orphics and has been significantly 
enhanced to include tight integration 
with the DirectDraw API. DirectBD 
consists of the following components: 
integrated retained mode and immedi- 
ate mode APIs, extensible file format, 
and a device- independent driver model 
for transparent access to 3D hardware 
acceleration. 

DirectBD is exposed to the devel- 



oper as COM - based interfaces for the 
retained (lDirect3DRl*l) and immediate 
mode APIs (iDirectSD). T hese interfaces 
are responsible for operations including 
DirectDraw rendering devices, textures, 
materials, lights, viewports, animations, 
and picl<ing. 

The DirectBD high-level retained- 
modeAPI is designed for manipulating 
BD objects and managing BD scenes, 
while insulating the developer from the 
mesh structures and transformation cal- 
culations. It is targeted at developers 
who don't want to create their own 
geometry engines or object database rou- 
tines but want to easily add BD capabili- 
ties to new or existing W indows- based 
applications. For example, the retained 
modeAPI supports the loading of a pre- 
defined, textured BD object with a single 
API command; the application can use 
additional simple API commands to 
rotate, move, or scale the object to 
manipulate it in the scene in real time. 
The retained modeAPI also supports 
l<ey frame animations. 

The DirectBD low-level immedi- 
ate-mode API , on the other hand, is a 
thin polygon- and vertex-based API 
layer that gives you direct access to fea- 
tures of BD hardware in a device-inde- 
pendent manner. Because the immedi- 
ate-mode API does not provide its own 
geometry engine (unlil<e the retained- 
modeAPI), the application handles the 
object and scene management. The 
immediate-mode API lets you port 
existing high-performance multimedia 
applications, such as games, to the W in- 
dows operating system. It also gives you 
the flexibility to mal<e use of your own 
rendering and scene- management tech- 
nologies while transparently tal<ing 
advantage of the new generation of BD 
hardware accelerators. 

D IrectBD provides a rich file format 
for storing meshes, textures, animation 
sets, and user- definable objects. This for- 
mat facilitates the exchange of BD infor- 
mation between applications. Support for 
animation sets allows predefined paths to 
be stored for playback in real time. 
Instancing and hierarchies are also sup- 
ported and allow multiple references to a 
single data object, such as a mesh, but 



store the data for the object only once per 
file. T he D IrectBD file format is used 
natively by the D IrectBD retained-mode 
API, providing support for reading pre- 
defined objects into an application or 
writing mesh information constructed by 
the application in real time. The file for- 
mat will be supported by content creators 
for modeling BD objects and scenes and 
defining complex animation paths, and it 
will be used by title developers for incor- 
poration into their titles. 

T he D IrectBD hardware abstraction 
layer (HAL) provides a driver interface 
for giving developers a transparent, 
device-independent means to access the 
features of BD hardware acceleration. 
The DirectBD hardware emulation layer 
(H EL) provides software- based emula- 
tion of BD rendering services not sup- 
ported by the hardware device. For 
example, DirectBD supports the acceler- 
ation of any or part of the BD rendering 
pipeline including transformations, 
lighting, and rasterization— many BD 
hardware accelerators on the market 
today only offload the rasterization mod- 
ule of the pipeline, so the transforma- 
tions and lighting are handled by the 
software emulation routines. This archi- 
tecture ensures that services exposed by 
the DirectBD APIs are always available 
to the application, whether the underly- 
ing hardware supports it or not. Devel- 
opers can query the underlying charac- 
teristics of the hardware to identify the 
capabilities supported and determine 
whether the hardware is providing the 
rendering services, to support tuning and 
scaling of the application in real time as 
appropriate for the given configuration. 

DirectBD integrates with Direct- 
Draw to provide 2D drawing and tex- 
ture services for BD rendering. A pplica- 
tions use D IrectBD and D IrectD raw for 
BD rendering in a relatively straightfor- 
ward manner. For example, the steps to 
set up a scene and to render a triangle 
using the D IrectBD immediate mode 
API are as follows: First, you use 
D IrectD raw to create the rendering sur- 
faces, which consist of the front buffer, 
back buffer, and (optionally) theZ- 
buffer, as DirectDraw surfaces. Next, 
you use th e IDirect3D COM i nterf ace to 
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set up the world, view, and projection 
matrices and to create a viewport to con- 
trol the 3D clipping information. You 
create a material for the bacl<ground of 
the viewport. You then create a D irect- 
D raw surface to serve as the texture for 
the triangle; then you create a material 
to define the surface reflectivity and 
color. Then you create a light source to 
add lighting to the scene. Next, create 
an execute buffer to represent the display 
list for holding the vertices and to define 
how the vertices are tied together into 
primitives for rendering the 3D object. 
You add any transformations, lighting, 
and rendering state information to the 
execute buffer, followed by the vertex 
and primitive operation information for 
representing the 3D object. Finally, you 
clear the viewport and render the exe- 
cute buffer, followed by a page flip oper- 
ation to display the rendered scene on 
the front buffer— repeat the process as 
the execute buffer is modified to ani- 
mate the object. 



Directlnput 

The joystick represents a class of 
devices that report tactile movements 
and actions that players make within a 
game. Directlnput provides the func- 
tionality to process the data represent- 
ing these movements and actions from 
joysticks, as well as other related 
devices, such as trackballs and flight 
harnesses. 

D irecti nput is currently another 
name for an existing W in32 function, 
joyGetPosEx. This function provides 
extended capabilities to its predecessor, 
joyGetPos, and should be used for any 
joystick services. In future support for 
input devices, including virtual reality 
hardware, games that use joyGetPosEx 
will be automatically supported for joy- 
stick input services. T his is not the case 
for joyGetPos. 

AutnPlay 

A utoPlay is the feature of W indows 95 
that automatically plays a CD or audio 



CD when inserted into a CD-ROM 
drive. Any CD-ROM product that 
bears the W indows 95 logo must be 
enabled with the A utoP lay feature. 

Game SDK COM Interfaces 

The interfaces in the Game SDK have 
been created at a very base level of the 
COM programming hierarchy. Each 
main device object interface, such as 

IDirectDrau, IDirectSound, or IDirectDrau 
derives directly from lUnknoun. The cre- 
ation of these base objects is handled by 
specialized functions in the library 
rather than by the W in32 CoCreateln- 
stance function normally used to create 
COM objects. T he G ame SD K object 
model provides one main object for 
each device, from which other support 
service objects are derived. For example, 
the DirectDraw object represents the dis- 
play adapter. It is used to create Direct- 
DrauSurface objects that represent the 
video RAM and DirectDrauPalette 
objects that represent hardware palettes. 
Similarly, the DirectSound object repre- 
sents the audio card and creates Direct- 
SoundBuffer objects that represent the 
sound sources on that card. 

Besides the ability to generate sub- 
ordinate objects, the main device object 
determines the capabilities of the hard- 
ware device it represents, such as the 
screen size and number of colors, or 
whether the audio card has wave table 
synthesis. 

By utilizing D irectX, it is finally 
possible to write state-of-the-art, fast- 
action, "rip the nerves from the tips of 
your fingers" games for W indows. And 
not only can these games far exceed the 
wildest dreams of W indows program- 
mers of the past, but they can leave 
DOS games twitching in the dust. 
W indows, it isn't just for spreadsheets 
anymore. ■ 

When not underwater basketweav- 
ing, Robert H ess spends his time as a soft- 
ware design engineer in the D ev eloper 
RelationsGroup at M io'osoft. You can con- 
tact him at gdmag@mfi.com. 

An extended version of this artide is 
avai lable on the I nternet at the G ame 
Developer web site 



28 GAME DEVELOPER - J UNE/J ULY 1996 



http:/ /wvvw.gdiTiag.com 



D I R E C T P L A Y 



Ne'tworking 
Your Game 
Using DirectPlay 



■ I in the advent of the W in- 
I A Pwsgs Game SDK, Win- 

■ f I wws 95 is now positioned 

■ 11 Ms a powerful and interest- 

■ I I Mng platform for network 

■ I IJgaming. M ore specifically, 
U Uthe D irectP lay component 

■ Bof the Game SDK provides 
a network communication protocol that 
stands to make life much easier for net- 
work game developers and players alike. 
It provides a device- and network-inde- 
pendent communications model for 
multiplayer games and a consistent user 
interface for establishing and maintain- 
ing network connections. 

DirectPlay provides all the over- 
head, which enables players to connect 
to each other in a consistent manner 
across a wide range of network types. At 
the code level, you simply call the correct 



D irectPlay A PI functions. T he one 
missing element in DirectPlay, however, 
is synchronization support. Because of 
the many different approaches to solving 
the game synchronization problem, 
D irectPlay forces you to implement your 
own game-specific solution. Although it 
might seem like M icrosoft took the easy 
way out, in reality they just didn't want 
to force a specific synchronization solu- 
tion on game developers. 

DirectPlay Architecture 

D irectPlay provides a network- indepen- 
dent programmatic interface to network 
game development. This network inde- 
pendence means that you write game- 
communication code to the DirectPlay 
API, and it sends the information over 
the network connection established for 
the game. This saves you from needing 



to learn the details of all the different 
network protocols. At this point, if you 
haven't breathed a huge sigh of relief, 
please feel free to. The ability to write 
network games without having to learn 
the details of network interfaces is truly 
a giant step in game programming. 
DirectPlay lets you focus on the network 
aspects directly related to your game. 

D irectPlay is composed of two 
parts: the DirectPlay COM (Compo- 
nent Object M odel) object and the 
DirectPlay service provider. The COM 
object provides the programmatic inter- 
face with which you establish network 
connections, maintain available sessions 
and players, and handle the details of 
sending and receiving game data. The 
DirectPlay service provider is a lower 
level D irectPlay component that handles 
the dirty work of implementing net- 
work-specific communications. The ser- 
vice provider is implemented as a net- 
work server for each type of supported 
network. M icrosoft provides DirectPlay 
servers for IPX, TCP/IP, and modem 
networks. Third-party vendors must 
develop their own D irectPlay servers for 
supporting specialized network hardware 
and online services. 

D irectPlay servers are the network 
game equivalents of drivers in other 
parts of the W indows system. Servers 
take on the difficulties of implementing 
the D irectPlay API for a specific net- 
work. This approach works well because 
it maintains a consistent interface at the 
application level, while allowing extensi- 
bility at the network level. W hen a 
D irectPlay C M object is created, a 
D irectPlay server is specified. D irectPlay 
then dynamically binds to this server. 
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Figure 1. The DirectPlay communications model. 
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through which all D irectPlay communi- 
cations are carried out. Figure 1 shows 
the D irectPlay communications model, 
which illustrates how an application 
communicates through D irectPlay on a 
particular type of network. 

DirectPlay Fundamentals 

D irectPlay provides a means of estab- 
lishing a connection and communicating 
over a network in a consistent manner. 
This is no small feat and puts a lot of 
responsibility on DirectPlay network 
servers. DirectPlay itself keeps up with 
information regarding the network con- 
nections and all parties involved. The 
key components of a D irectPlay network 
connection are sessions and players. 

Sessions 

Every D irectPlay game must establish a 
session, which is a communication 
channel. M ultiple sessions on a given 
network correspond to different multi- 
player games running on the network. 
The exception is a modem network. 



where only one session can exist. Play- 
ers in a particular network game are in 
the same session. Suppose you want to 
join one of two sessions of a network 
Poker game. You must choose one 
poker game or the other to connect to. 
Players choose from a list of sessions 
that D irectPlay supports. 

DirectPlay can save information 
about a session in the registry for future 
use. W ith a modem network, for exam- 
ple, the remote player's name, phone 
number, and optional password are 
saved. Speaking of modem connections, 
modem code is another huge responsi- 
bility taken on by DirectPlay. Remem- 
ber that DirectPlay servers handle the 
details of actually making the network 
connections. The DirectPlay modem 
server uses the W indows 95 Telephony 
Application Programming Interface 
(TAPI) to manage the intricacies of 
modem connections. 

To join a DirectPlay game, you 
connect to an existing session on the 
network. Because this connection usually 
takes place from 



Listing 1. The CGame::DPInit Member Function forTicTacToe 



CGame::DPInit() 
{ 

// Clear the players 
in.dpidPlayer[0] = 0; 
in.dpidPlayer[l] = 0; 

// Prompt user to select a DP server, then create the DP 
object 

CServerSelDlg dlgServerSel; 
if (dlgServerSel.DoHodalO == IDOK) 
return (: :DirectPlayCreate{dlgServerSel.GetSelServer(), 
ta.pDirectPlay, NULL) == DPJK); 

return PULSE; 



within a game, you 
select from the list 
of sessions that typ- 
ically shows only 
one type of game. 
I n other words, if 
you run a C hess 
game and try to 
connect to a ses- 
sion, it will only 
show you other 
C hess sessions on 
the network. This 
limiting of sessions 
is implemented at 
the application 
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Michael Morrison 

DirectPlay takes care 
of developing a 

network- based game 
while shielding you 

from all those messy 

network protocol and 
modem details, 
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Figure 2. DirectPlay client/server session connections. 



level, so it is technically possible to stiow 
all available sessions of all game types, 
which might be useful in a game finder 
application that shows all game sessions 
and then launches the appropriate one 
based on the user's choice. 

H ow are sessions created to begin 
with? The original player is responsible 
for initially creating the game session to 
which other players will connect. When 
creating a new session, you assign a 
name to it so other players can find it, 
such as "Bill's N o-H olds-Barred Cage 
M atch." Because all available sessions are 
lil<ely to be for the same type of game, it 
is important for you to give your session 
an identifiable name. Then just sit bacl< 
and wait for someone to connect to your 
session so you can get down to business. 

Each type of session must be 
assigned a global identifier, which is 
guaranteed to be unique for all sessions. 
D irectPlay uses this identifier when 
referring to the session internally. This is 
how DirectPlay keeps up with games 
created independently. You can generate 
a global identifier for your game by run- 
ning U U I D G E N , which is an applica- 
tion that comes with theW in32 SDK. It 
requires a networl< card to generate 
unique identifiers, since all networl< 
cards have a unique identifier associated 
with them. 



You might have noticed that 
D irectPlay imposes a client/ server model 
for initially connecting to game sessions. 
ne of the players must perform the ini- 
tial session creation. This is the server 
game. All other players connect to this 
game as clients. After connections are 
made, it doesn't matter who made the 
initial connection. In this way, the 
client/server model is in effect only dur- 
ing the initial session creation and con- 
nection. Figure 2 shows multiple client 
players connecting to a game created by 
the server player. 

Players 

DirectPlay maintains a list of current 
players in a session and provides an inter- 
face to manage them. Each player gener- 
ally corresponds to other game instances 
on the network. E ach player has a friend- 
ly name and a formal name that are set 
when the player is created, as well as a 
player identifier (I D ). D irectPlay does not 
use the player names internally; they are 
solely for player communication during 
the game or for a high score list. D irect- 
Play always uses a player's identifier when 
working with players internally. 

DirectPlay also supports player 
groups, which can be thought of as 
teams. A player group appears like a 
player in the session. Information then 



can be sent to the group, in which case 
DirectPlay routes the message to each 
individual player in the group. 

Messages 

D irectPlay manages communication 
between players. D irectPlay messages are 
different from W indows messages and 
are sent and received through a different 
protocol. A few DirectPlay system mes- 
sages let you determine when a connec- 
tion has been established and when play- 
ers and groups have been added or delet- 
ed. Other messages are custom, game- 
specific messages that you define. To 
send a message to another player, you 
simply call the appropriate DirectPlay 
function and provide the I D of the play- 
er with the message to be sent. T he tar- 
get game then receives the message and 
processes it accordingly. 

DirectPlay Implementation 

D irectPlay is implemented as a C M 
object that represents the entire commu- 
nications environment for an applica- 
tion. T he D irectPlay C M object, 
DirectPlay, provides access to Direct- 
Play's functionality. DirectPlay contains 
two API functions used to enumerate 
D irectPlay servers and create DirectPlay 
objects. You always use one of these 
functions to create an initial DirectPlay 
object. In fact, you will usually use both 
functions; you will enumerate and dis- 
play the available D irectPlay servers and 
then create a DirectPlay object based on 
the server selected by the user. The 
D irectPlay API functions are DirectPlay- 
Create and DirectPlayEnumerate. 

DirectPlayCreate creates and initial- 
izes a DirectPlay object: 

HRESULT DirectPlayCreatedPGUID IpGUID, 
LPDIRECTPLAY FAR *lplpDP, 
lUnknoun FAR * pUnkOuter) 

DirectPlayEnumerate is the Other half 
of the D irectPlay API function pair, 
which is used to query the system for the 
available network service providers: 

HRESULT DirectPlayEnumerateCLPDPENUMDP- 
CALLBACK IpEnumDPCallback, 
LPVOID IpContext) 
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Each installed network service 
provider contains an entry in the reg- 
istry. DirectPlayEnumerate searches for 
these entries and notifies you of each 
supported network server. Practically 
speaking, you will always want to enu- 
merate and display the available network 
servers so the user can select from them. 
After the user selects a server, you pass 
its global identifier into DirectPlayCreate 
to create the DirectPiay object and bind 
it to the selected network server. 

The DirectPiay object itself repre- 
sents the physical network connection 
and associated information about the 
connection. To create the DirectPiay 
object, you specify which DirectPiay 
server the object will bind to for actual 
communication. Once the DirectPiay 
object is created, you can establish a net- 
work connection. W hen you get a point- 
er to a DirectPiay object via a call to 
DirectPlayCreate, you don't have a point- 
er to the DirectPiay object itself; you 
have a pointer to the iDirectPlay inter- 
face of the DirectPiay object. The IDi- 
rectPlay interface defines the functions 
implemented by the DirectPiay object. 
The most useful functions supported by 
the IDirectPlay interface are: Close, Enum- 
Sessions, Open, CreatePlayer, GetCaps, 
Receive, DestroyPlayer, GetHessageCount, 
SaueSession, EnableNeuPlayers, GetPlayer- 
Caps, Send, EnumPlayers, GetPlayerName, 
and SetPlayerNaitie. 

The Close member function, HRE- 
SULT IDirectPlay: :Close(), closes the 
communications channel (session) for 
the DirectPiay object. 

This means the session will be 
closed, and all communications will be 
stopped. Because Close ultimately 
destroys the session connection, you 
always must destroy any local players 
before calling it. Some service providers 
will not allow a session to close until all 
players have been destroyed. This is 
especially important when the player 
who created the session tries to close it. 

The CreatePlayer member function 
creates a player for a particular session: 

HRESULT IDirectPlay: :CreatePlayer(LPDPID 
IpDPId, LPSTR 

IpPlayerFriendlyName, LPSTR IpPlayer- 



FormalName, 
LPHANDLE IpReceiveEvent) 

After you create or connect to a ses- 
sion, you call CreatePlayer to create a 
local player. When you successfully cre- 
ate a new player using CreatePlayer, 
DirectPiay sends a DPSYS.ADDPLAYER sys- 
tem message to all other players in the 
session notifying them of the new player. 
You are allowed to create multiple local 
players, in which you use a single 
machine for multiple player interaction. 
An example of this scenario is having 
two joysticks connected to one machine. 
D irectPlay imposes no limitations on the 
number of local and remote players, 
although you can limit the number of 
players that can be added to your game. 

T he DestroyPlayer member function 
destroys a player from a game session: 



ers (BOOL bEnable) 

The EnumPlayers member function 
enumerates the current players in a session: 

HRESULT IDirectPlay: : EnumPlayers 
(LPDPENUMPLAYERSCALLBACK 

IpEnuinPlayersCallback, LPVOID IpCon- 
text, DWORD duFlags) 

The EnumSessions member function 
enumerates the current game sessions: 

HRESULT IDirectPlay: : EnumSessions 
(LPDPSESSIONDESC IpDPSessionDesc , 

LPDPENUMSESSIONSCALLBACK IpEnumSes- 
sionCallback, LPVOID 
IpContext, DWORD duFlags) 

EnumSessions is used to build a list of 
the available sessions, in which you can 



HRESULT IDirect- 
Play : :DestroyPlay- 
er(DPID DPId) 

You must call 
DestroyPlayer to 
destroy any local 
players you have cre- 
ated before closing 
the game session. 
After you successful- 
ly destroy a player 
using DestroyPlayer, 
D IrectPlay sends a 
DPSYS.DELETEPLAYER 

system message to 
all the other players 
in the session notify- 
ing them of the 
player exiting the 
session. 

T he EnableNeu- 
Players member func- 
tion toggles the 
capability to add new 
players and groups to 
a session and can be 
used to keep other 
players from joining 
a session: 

HRESULT IDirect- 
Play : : EnableNeuPlay- 



Listing 2. The CGamenDPCreateSession IVIetnber Function for TicTacToe 



BOOL 

CGame: :DPCreateSession() 
{ 

if (m pDirectPlay) 
{ 

// Get session information 
CSessionlnfoDlg dlgSessionlnfo; 
if (dlgSessionlnfo. DoModalO == IDOK) 
{ 

// Create a new DP session 
DPSESSIONDESC dpsdDesc; 

: :Zeroneiiiory(&dpsdDesc, sizeof (DPSESSIONDESC)); 
dpsdDesc. dwSize = sizeof (DPSESSIONDESC); 
dpsdDesc. duHaxPlayers = 2; 
dpsdDesc. duFlags = DPOPEN.CREATESESSION; 
dpsdDesc. guidSession = TICTACTOE.IO; 

: : strcpy (dpsdDesc . szSessionName, dlgSessionlnfo . Get- 

NameO); 

if (m pDirectPlay->Open(MpsdDesc) == DP.OK) 
{ 

// Create local player and set game info 
iii.pDirectPlay->EnableNeuPlayers(TRUE); 
if (DPCreateLocalPlayerO) 
{ 

DPCreateEventThreadO; 
m.bHyTurn = TRUE; 
return TRUE; 

} 

} 

} 

} 

return FALSE; 

} 
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Figure 3. The TicTacToe sample game. 



provide an interface for tiie user to seiect 
a session to join. Ttiistectinique is useful 
on the client end of a game connection, 
because it lool<s for preexisting game ses- 
sions to select from. 

The GetCaps member function gets 
the capabilities of the DirectPlay object, 
which is dependent on the networl< serv- 
er to which the object is bound: 

HRESULT IDirectPlay:: GetCaps (LPDPCAPS 
IpDPCaps) 

T he GetMessageCount member func- 
tion determines the number of Direct- 
Play messages waiting for a particular 
player and is used to determine when to 
receive messages for a player: 

HRESULT IDirectPlay: : GetMessageCount 
(DPID DPId, LPDWORD IpduCount) 



T he GetPlayerCaps member function 
retrieves the capabilities of a particular 
player: 

HRESULT IDirectPlay: :GetPlayerCaps 
(DPID DPId, LPDPCAPS IpDPPlayerCaps) 

T he GetPlayerName member function 
queries D irectPlay for a player's friendly 
and formal names: 

HRESULT IDirectPlay: :GetPlayerName 
(DPID DPId, LPSTR IpFriendlyName, 
LPDWORD IpduFriendlyNameLength, LPSTR 
IpFormalName, LPDWORD IpduFormalName- 
Length) 

The GetPlayerName function is very 
useful if you want to notify others about 
a player's actions— for example, a player 
leaving the game. 

The Open member function opens 
the DirectPlay object and establishes a 
networl< connection, which means either 
creating a new session or connecting to 
an existing session: 

HRESULT IDirectPlay: :Open(LPDPSESSIONDE- 
SC IpDPSessionDesc) 

T he user interface required to actu- 
ally establish the connection is handled 
by DirectPlay, such as the dialing inter- 
face for a modem connection. 

The Receive member function 
receives pending messages for a player: 

HRESULT IDirectPlay: :Receive(LPDPID 
IpDPIdFroin, LPDPID IpDPIdTo, 
DWORD duReceiueaags, LPSTR IpHessage, 



Listing 3. The CGameDPCreateLocalPlayer Member Function for TicTacToe 



BOOL 

CGame: :DPCreateLocalPlayer{) 
{ 

// Create local DP player 
CPlayerlnfoDlg dlgPlayerlnfo; 
if (dlgPlayerlnfo. DoModalO == IDOK) 
return (in_pDirectPlay->CreatePlayer(ta_dpidPlayer[0] , 

dlgPlayerlnfo. GetPriendlyNameO , 

dTgPlayerlnfo.GetPormalNameO, ta.hDPEvent) == DP.OK); 

return FALSE; 

} 



LPDWORD IpduLength) 

You use this function to receive 
information from other players and 
from D irectPlay regarding the status of 
the game. Receive always processes mes- 
sages with respect to a particular player. 
D irectPlay has a set of system messages 
with corresponding structures contain- 
ing information specific to the system 
message. You can access the informa- 
tion in each system message first by 
casting the message data to the generic 
message structure, DPMSG.GENERIC, and 
looking at the duType message type 
member. The message type will corre- 
spond to one of the DirectPlay system 
messages. nee you l<now the type, you 
then can cast the data to the message 
structure of the appropriate type to 
access the message- specific data. 

The SaveSession member function 
saves information regarding the current 
session to the registry: 

HRESULT IDirectPlay: :SaveSession(LPSTR 
IpName) 

This includes information, such as 
the player's friendly and formal names 
and phone number, in the case of a 
modem connection. 

The Send member function is the 
companion to Receive and is used to 
send information to other players in the 
session: 

HRESULT IDirectPlay: :Send(DPID DPIdFrom, 
DPID DPIdTo, DWORD 

duFlags, LPSTR IpMessage, DWORD 
duLength) 



T he SetPlayerName member function 




Figure 4. The TicTacToe Server 
Selection dialog box. 
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sets the friendly and formal names of a 
player: 

HRESULT IDirectPlay: :SetPlayerNaine(DPID 
DPId, LPSTR 
IpFriendlyNaine, LPSTR IpFormalName) 



Using DirectPlay in Games 

The first function of a D irectPlay game 
is to determine whether the user intends 
to create a new session or connect to an 
existing session. This function is accom- 
plished through some type of user inter- 
face, as determined by the D irectPlay 
service provider. After the user decides 
whether to create a new session or con- 
nect to an existing session, the DirectPlay 
object must be created and opened with 
the proper settings. 

T he next step is to create local play- 
ers for the session. After the session is 
open and the players are created, the 
game is ready to begin. Remember, the 
same application will be running on both 
ends, so all players will be visible to each 
other as soon as they are created. The 
game then begins, and the play carries 
on in a way determined by your game- 
specific messaging protocol. 

In addition to handling your own 
messages, you need to handle D irectPlay 
system messages. T his is very important 
because it is possible for players to drop 
out of the game, in which case you will 
get a system message indicating that the 
player has left the session. 

TicTacToe is a sample game that 
uses D irectPlay to manage network 
communications for two players. It is a 
very simple turn- based game that shows 
the basics of DirectPlay communication. 
Figure 3 shows what TicTacToe looks 
likeduring a game. 

Running TicTacToe 

The TicTacToe main menu contains a 
Game pull-down menu with the fol- 
lowing menu choices: Create, Connect, 
E nd, and E xit. C reate makes a new 
network session. Connect joins to an 
existing network session. End stops a 
network session, and Exit terminates 
the application. To establish a two- 
player network connection, one player 



creates a new session and the other 
player connects to it. So, the server 
player first must choose Create from 
the menu, which causes the Server 
Selection dialog box (shown in Figure 
4) to appear. 

In the example in Figure 4, a 
modem connection has been selected. 
The Enter Session Information dialog 
box appears and prompts for the name 
of the new session. After you enter the 
session information, the session is 
opened and the Enter Player Informa- 
tion dialog box appears. H ere, you enter 
information regarding the local player, 
yourself. 

TicTacToe then 

creates a player using the 
friendly and formal 
names you entered in the 
Enter Player Information 
dialog box. At this point, 
a new session has been 
created with a player rep- 
resenting you, the local 
player. N ow you just sit 
back and wait for a 
remote player to join in. 

n the remote end, 
the player chooses Con- 
nect from the G ame 
menu. H e or she must 
choose a modem con- 
nection from the Server 
Selection dialog box, 
just as you did. After 
selecting the network 
server, things change. 
I nstead of specifying a 
new session name, the 
remote player is prompt- 
ed with a list of available 
sessions from which to 
choose. In this case, 
there is only a single 
entry for dialing up a 
modem session. 

After selecting the 
modem dial session, the 
remote player sees the 
D iai dialog box. T he 
D irectPlay model server 
handles this interface. 

A fter the remote 
player specifies the 



phone number of the server session, 
DirectPlay dials the number and estab- 
lishes the modem connection. nee con- 
nected, the remote player must enter his 
or her own player information so that 
D irectPlay can create a local player. After 
entering player information, the remote 
player then sees a list of players currently 
in the game and must select one to play 
with. Of course, in TicTacToe, there is 
always just one other player. The main 
reason for including this feature in Tic- 
TacToe is to show how to enumerate 
other players when joining a session. T he 
remote player must select the server player 
from a Player Selection dialog box. 



Listing 4. Tlie CGame::DPConnectSession IVIember Function for TicTacToe 



BOOL 

CGame: :DPConnectSession() 
{ 

if (m.pDirectPlay) 
{ 

// Select a DP session 
CSessionSelDlg dlgSessionSeldn.pDirectPlaj) ; 
if (dlgSessionSel.DoModalO == IDOK) 
{ 

// Open remote DP session 
DPSESSIONDESC dpsdDesc; 

: :Zero[1einory{MpsdDesc, sizeof (DPSESSIONDESC)); 
dpsdDesc. dwSize = sizeof (DPSESSIONDESC); 
dpsdDesc. dwFlags = DPOPEN.OPENSESSION; 
dpsdDesc. guidSession = TICTACTOE.IO; 
dpsdDesc. dwSession = dlgSessionSel.GetSelSessionO; 
if (m pDirectPlay->Open(&dpsdDesc) == DP OK) 
{ 

// Prompt user to select the remote player 
CPlayerSelDlg dlgPlayerSeKm.pDirectPlay) ; 
if (dlgPlayerSel.DoNodalO == IDOK) 
{ 

// Set remote player 

m_dpidPlayer[l] = dlgPlayerSel.GetSelPlayerO; 
// Create local player and set game info 
m.pDirectPlay->EnableNewPlayers(TRUE); 
if (DPCreateLocalPlayerO) 
{ 

DPCreateE«entThread(); 
m.bHyTurn = FALSE; 
NeuGameO; 
return TRUE; 

} 



} 



} 



} 

} 

} 

return FALSE; 
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Listing 5. The CGame::DPEventlVlsg IVIember Function for TicTacToe 



UINT 

CGame: :OPEventl1sgStart{LPV0ID pData) 
{ 

// Call the DP event handler 
*SSERT{(CGaiiie*)pData); 
{(CGaiiie*)pData)->DPEventl1sg() ; 
return 0; 

} 

void 

CGame: :DPEventl1sg() 
{ 

uhile(TRUE) 
{ 

// Kait for event 

if (::WaitForSingleObject(iii.hDPEvent, INFINITE) != 
WAH HHEOUT) 

{ 

// Process event message 
if (m.pDirectPlay) 
{ 

DPID dpidFrom, dpidTo; 
BYTE [1sg[256]; 
DyORD duLen = 128; 

if (in_pDirectPlay->Receive{&dpidFrom, MpidTo, 
DPRECEIVE ALL, Msg, iduLen) == DP OK) 

{ 

if (dpidFrom = 0) 
{ 

// Got a system message 

DPMSG.GENERIC* pmsgGeneric = (DPHSG.GENERIC*)Hsg; 
CString sText; 
suitch{pmsgGeneric->duType) 
{ 

case DPSYS.CONNECT: 

Af xGetHainWnd ( ) ->MessageBox ( "Connected ! " , 
AfxGetAppNameO); 

break; 
case DPSYS.SESSIONLOST: 

AfxGetHainlilnd()->MessageBox("Session lost!", } 
AfxGetAppNameO); } 

DPQeanupO; } 

break; } 
case DPSYSJDDPLAYER: } 

// Notify of new player 

sText.FormatC'New Player : '/.s", ((DPHSG.ADDPLAYER+) 



pmsgGeneric)->szShortName) ; 
AfxGetMainUnd()->HessageBox(sText, 

AfxGetAppNameO); 
// Set new player and start new game 
if (((DPNSG.ADDPLAYER*)pmsgGeneric)->dpId != 
m_dpidPlayer[0]) 

{ 

m.dpidPlayer[l] = ((DPNSG.ADDPLAYER*) 

pmsgGeneric)->dpId; 
NeuGameO; 

} 

break; 

case DPSYS.DELETEPLAYER: 
AfxGetHainWnd()->MessageBox("Player Deleted!", 
AfxGetAppNameO); 
if (((DPMSG.DELETEPLAYER*)pmsgGeneric)->dpId == 
m_dpidPlayer[l]) 

{ 

m.dpidPlayer[l] = 0; 
DPEndSessionO; 

} 

break; 

} 

} 

else 

if (dpidTo == m_dpidPlayer[0]) 
{ 

// Got a remote player turn message 
if (dwLen == sizeof(POINT)) 
{ 

CPoint ptTLLe(*((POINT*)Nsg)); 
DPReceiveTurnHsg(ptTile) ; 

} 

else 

AfxGetMainUnd()->HessageBox( 
"Unknown player message.", AfxGetAppNameO); 

} 



T icT acT oe is set up SO that the serv- 
er player always gets to go first. Even so, 
it is important for the remote player to 
know that the game has begun. That is 
the reason for notifying the remote player 
of the server player's turn. At this point, 
the game has begun, and the remote play- 
er is waiting for the server player to make 
the first move. 

Let's jump back to the server side of 



things for a moment. W hen the remote 
player first connected to the server ses- 
sion, the server player received a connec- 
tion system message. After being notified 
of the remote player's connection, the 
server player is sent an AddPlayer message 
containing information about the remote 
player. At this point, the server side now 
knows about the remote connection and 
the remote player, so the game begins. 



Regardless of the outcome, the 
player who was to go next starts the next 
game playing Xs. And the game goes on 
until one of the players ends the session 
by choosing End from the Game menu 
or by closing the application. 

Under The Hood 

N ow that you've got a feel for how T ic- 
T acT oe runs, let's take a look at how it 
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works. T he code that supports D irect- 
Play is mostly located in the CGame 
class. Incidentally, all the source code 
files for the TicTacToe game can be 
found on the Game D eveloper web site. 

T he CGame class models the T icT ac- 
Toe game itself and maintains the 
DirectPlay connection, along with the 
players and the game- synchronization 
logic. CGame keeps a pointer to the 
DirectPlay object in m.pDirectPlay. This 
pointer is set by the DPinit member 
function, which is called by the applica- 
tion to initialize DirectPlay services for 
the game T he source code for DPinit is 
shown in Listing 1. 

DPinit initializes the player mem- 
bers, m_dpidPlayer[2], and prompts the 
user to select a network game server by 
using the dialog object cserverSelDlg. 
The server identifier retrieved from the 
Server Selection dialog box then creates 
the DirectPlay object by calling Direct- 
PlayCreate. 

DPCleanup is the corresponding 
member function for cleaning up the 
DirectPlay support. It first calls DPEnd- 
Session, which destroys the local player 
by calling DPDestroyLocalPlayer. It closes 
the DirectPlay object and deletes the 
DirectPlay event thread used to process 
messages. Then DPCleanup releases the 
DirectPlay object and NULLS the member 
pointer. 

CGame creates a D irectPlay session 
through the DPCreateSession member 
function, as shown in L isting 2. 

DPCreateSession first prompts for 
the name of the new session by using 
the CSessionlnfoDlg dialog object. It 
then uses this name to help fill out a 
DPSESSIONDESC Structure that passes into 
the Open member function of the Direct- 
Play object. The maximum number of 
players is set to 2 and the open flag is 
set to DPOPEN.CREATESESSION. The session 
identifier is set to tictactoe.io, which 
specifies that this is version 1.0 of T ic- 
TacToe. TICTACTOE.IO is a global identi- 
fier that uniquely identifies the TicTac- 
Toe game. It was obtained by running 
the UUIDGEN application, and is 
defined in thefileGUID.H . 

After opening the new session, 
DPCreateSession enables the addition of 



new players and calls DPCreateLocal Play- 
er. The source code for DPCreateLocal 
Player is shown in Listing 3. 

DPCreateLocalPlayer displays a dialog 
box using the CPiayerinfoDig dialog object 
to obtain the friendly and formal names 
of the new player. It then uses these 
names in a call to the DirectPlay object's 
CreatePlayer member function to create 
the local player. You'll notice that Cre- 
atePlayer is passed a pointer to an event 
handle, m_hDPEvent, as its last parameter. 
This event handle specifies a W in32 Manu- 
al Reset event that is signaled when the 
player has waiting messages. After creat- 
ing the local player, DPCreateSession cre- 
ates an event thread by calling DPCre- 
ateEventThread. Finally, DPCreateSession 
sets the turn member variable, m.bHyTurn, 
to TRUE, which indicates that the server 
side of the game goes first. At this point, 
the session has been created and the local 
player is eagerly awaiting a connection by 
another player. 

So how does the remote player con- 
nect to an existing session, like the one 
created by the server player with DPCreate- 
Session? DPConnectSession connects to 
existing sessions and is very similar to 
DPCreateSession. T he primary difference is 
that DPConnectSession displays the Session 
Selection dialog box using the CSession- 
SeiDig dialog object, instead of prompting 
for information regarding a new session. 
T he DPOPEN.OPENSESSiON flag is used in the 
DPSESSIONDESC Structure to specify that you 
are attempting to open an existing ses- 
sion. The source code 
for DPConnectSession is 
shown in Listing 4. 

After opening 
the session, the local 
player is prompted to 
select the server play- 
er from the dialog box 
displayed by the 
CPlayerSelDlg dialog 
object. The identifier 
of this player is stored 
away for later com- 
munication, and the 
local player is created 
by calling DPCreateLo- 
calPlayer. T he player 
event thread is then 



created, and the m.bHyTurn member vari- 
able is set to FALSE to indicate that the 
client player goes second. Finally, a new 
game is started. 

D uring the course of the game, all 
DirectPlay messages are processed by 
the DPEventMsg member function (List- 
ing 5). T his function is called automati- 
cally when a D irectPlay event occurs. 

The first call is to WaitForSingleOb- 
ject, which is a W in32 API function 
that waits for an event to be signaled 
before returning. T he significance of 
WaitForSingleObject is that it remains in a 
sleep state while waiting for the event to 
occur. You specify an infinite time-out 
period so that it will never time out. 

The first step in processing Direct- 
Play messages is to receive the message 
and check the identifier of the source 
player to see whether it is a system mes- 
sage. System messages always are sent 
from player 0. If the message is a sys- 
tem message, you cast the data to a 
generic message structure to get the 
type of message. If a player has been 
added, you notify the local player, set 
the remote player identifier member 
variable, and start a new game. This 
scenario occurs when a remote player 
connects to a session created by the 
local player. I f a player is deleted, which 
would correspond to the remote player 
quitting, the local player is notified and 
the session is terminated. 

If the message is not a system mes- 
sage, the message is cast to a point struc- 



Listing B. Tlie CGame::DPReceiveTurnMsg Member Function for TicTacToe 



BOOL 

CGame: :DPReceiweTurnMsg(CPointSi ptTHe) 
{ 

// Check remote turn message for valid tile bounds 
if ((ptTile.x >= 0) m (ptTile.x <= 2) Ml (ptTile.y >= 0) 
(ptTile.y <= 2)) 

{ 

// Update game with remote turn data 
SetTileState(ptTile.x, ptTile.y); 



return TRUE; 



} 



return FALSE; 



} 
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ture and passed to DPReceiveTurnMsg. 
DPReceiveTurnPisg notifies the local game 
of the remote player's move, as shown in 
Listing 6. 

The game- specific messages sent 
between players correspond to coordi- 
nates on theTicTacToe grid. These coor- 
dinates are used to specify each player's 
move. A POINT structure is used to pass 
this information in DPReceiveTurnMsg. 
DPReceiveTurnMsg receives this Structure 
and sets the state of the grid tile to the 
appropriate value, X or 0, by calling Set- 
TileState. 

SetTileState is the workhorse 
function for maintaining the state of 
the game. It is passed the X and Y val- 
ues of the grid tile to be set. It first 
checl<s to make sure that the tile is 
empty. It then checks whether it is the 



local player's turn, in which case it 
sends the tile coordinates to the remote 
player to signify the move. T his is han- 
dled by calling DPSendTurnHsg. DPSend- 
TurnMsg simply calls the DirectPlay 
object's Send member function with the 
proper parameters. After updating the 
remote game, SetTileState updates the 
local game by changing turns, setting 
the tile state, and updating the window 
so that the new tile state is displayed. 
The source code for SetTileState is 
shown in L isting 7. 

After setting the new tile state in 
both games, SetTileState proceeds to 
check for a win or draw by calling IsWin- 
ner and isDrau. T hese two functions con- 
tain the logic for determining whether a 
player has won the game or whether the 
game is a draw. That's it! 



You've seen first hand how you can 
use D irectPlay to create a fully function- 
ing network game. A I most every aspect of 
using DirectPlay was touched on, along 
with sample code for you to reuse in your 
own games. 

Although a practical network game 
implementation often gets messy, you 
have the building blocks required to 
frame up a network game so you can 
focus on synchronization details. You also 
have some pretty clean interface objects to 
use for working with D irectPlay. You 
have all you need to go write a cool net- 
work game for Windows 95! ■ 

M idiael M orrison is the co-author of 
W indows 95 G ame D eveloper's G uide 
to Using the Game SDK. You can ODntact 
him via e-mail at gdmag@mfi.ODm. 



Listing 7. The CGame::SetTileState Member Function for TicTacToe 



: BOOL 
CGaiiie::SetTileState(UINT uiX, UINT uiY) 
{ 

IISSERT{(uil( < 3) M (uiY < 3)); 
Cyaue uavTHe; 

if (m tsGrid[uiX][uiY] == tsEHPTY) 
{ 

// Send tHe info to remote player via a turn message 
if (m.bHyTurn) 

if {!DPSendTurnnsg{CPoint(ui)(, uiY))) 

{ 

AfxGet[1ainUnd()->HessageBox("Error sending turn message.", 

AfxGetAppNameO); 
return FALSE; 

} 

// Change turns and set the tile state 
m.bHyTurn = Im.bMyTurn; 

m.tsGrid[uiJ(][uiY] = (m.uiTurns '/. 2) ? tsO : tsX; 
// Update grid 

llf xGetMainUnd ( ) ->InvalLdate( FALSE) ; 
// Play the tile wave 

uavTiLe.Create{(m.uiTurns '/. 2) ? IQy.O : IQyj); 
uavTiLe.PlayO; 

} 

else 
{ 

// Play the tile error wave 
uavTiLe.CreatedDy.ERROR); 
uavTHe.PlayO; 
return FALSE; 

} 

// Check for winner/draw 

if (IsWinnerO) 

{ 



// Determine winner and notify 

if (m bMyTurn) 

{ 

Cyave uavLose(IDy.LOSE); 
wavLose.PlayO; 

AfxGetHainynd()->BessageBox("Bummer, you lost!", 
AfxGetAppNameO); 

} 

else 
{ 

cyave wavyin(IDy.yiN); 
wavyin.PlayO; 

AfxGetHainynd()->MessageBox("Congratulations, you won!", 
AfxGetAppNameO); 

} 

// Start new game 
return NewGameO; 

} 

else 
{ 

if (IsDrawO) 
{ 

// Play draw wave 
cyave uavDraw(IDy.DRAy); 
wavDrau.PlayO; 
// Notify of a draw 

AfxGetHainynd()->MessageBox("It's a drawl", AfxGetAppNameO); 
// Start new game 
return NewGameO; 

} 

} 

return TRUE; 

} 
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Di r e c t:S o u n d 
Unplugged 



Sound is a powerful, expressive 
medium— more powerful, I 
believe, than even our visual 
sense for conveying informa- 
tion and emotion. John Rat- 
cliff, designer of Seawolf and 
688 Attack Sub, has a 
favorite example of sound's 
impact: compare a tyrannosaurus rex 
scene in Jurassic Park both with and 
without the sound track. 

M y example is even more dramatic: 
imagine you watch the great opera La 



Bohemein New York City, but you wear 
earplugs. N ow, although you may actually 
find the music tolerable under this condi- 
tion, opera without sound is essentially 
just a bunch of fat mimes. And who 
wants to watch that for three hours? 

So there's really no doubt about how 
much atmosphere sound can add to a 
game. Unfortunately, the Windows A Pis 
traditionally have given short shrift to 
audio. W ell, no longer— under W indows 
95, DirectSound allows you to do every- 
thing you could do by accessing the hard- 



ware directly, and, as a bonus, provides a 
solid base for future sound technology 
developments. 

In this article, we'll discuss every- 
thing you need to know to add Direct- 
Sound to your application. W e've only 
got four thousand words to do it— which 
isn't a lot (my bad memories of writing 
class notwithstanding), so we're going to 
have to cruise. Buckled in? 

This is Not an Overview 

N ormally, the folks at Game D eveloper 
magazine respond to the word "overview" 
like a French chef would respond to a 
request for ketchup. So, to keep the edi- 
torial saliva out of my alphabet soup, we'll 
zoom through this section as quickly as 
we can. 

First, the D irectSound API is based 
on the Component Object Model 
(COM ). COM arrived with L E , but it 
can stand alone as a standard way to pre- 
sent an API to an application. It letsC-H- 
people access the API with nice object- 
oriented code, and it lets C people access 
the A PI with weird macros. We'll show 
both types of calling sequences in this 
article. 

COM -based APIs are all used the 
same way. You call a Create function that 
returns a pointer to an object (C pro- 
grammers read "structure"). This object 
contains the important data, as well as 
member functions (C programmers read 
"function pointers") that operate on the 
object. So, with COM , everything the 
API can do is accessed through an object. 

I n the D irectSound COM A PI , we 
find two objects: the DirectSound object 
and the DirectSoundBuffer object. You 
create the DirectSound object to gain 



Listing 1. A Function tliat Creates Awesome Secondary Buffers 



HRESULT CreateDSBufferdPDIRECTSOUND IpDS, LPDIRECTSOUNDBUFFER ♦ IplpDSB, 
DWORD SoundBytes, DWORD Frequency, int IsStereo, int Isl6Bit) 

{ 

DSBUFFERDESC dsbd; 

PCHyAVEFORMAT fmt; 

f mt . uf . nChannels=(IsStereo) ?2 : 1 ; 

fmt . uBitsPerSainple=(Isl6Bit) ?16 : 8 ; 

f mt . uf . nSainplesPerSec=( (DyORD) Frequency ) ; 

fmt . uf . nBlockAlLgn=f mt . uf . nChannels*(f mt . uBitsPerSample»3) ; 

fmt.uf.n*vgBytesPerSec=((DWORD)fmt.uf.nSamplesPerSec)*((DyORD)fmt.uf.nBlockAlLgn); 

f mt . uf . uFormatTag=WAVE.F0R[1AT.PC[1 ; 

memsetC idsbd, 0, sizeof(dsbd) ); 

dsbd.lpufxFormat=(LPWAVEFORn*TEX)&fmt; 

dsbd . duSize=sizeof (DSBUFFERDESC) ; 

dsbd . duBuf f erBy tes=SoundBytes ; 

dsbd.duFlags=0; 

In C++: return( lpDS->CreateSoundBuffer( Msbd, IplpDSB, 0) ); 
In C: return( IDirectSound CreateSoundBuffer( IpDS, Msbd, IplpDSB, 0) ); 
} 

// Sample use of the CreateDSBuffer function 
LPDIRECTSOUNDBUFFER IpDSB; 

if (CreateDSBuffer ( IpDS, EpDSB, TotalSoundBytes, 22050, , 0) ) { // Open 22050, mono, 
8 bit sample 

// Use the DirectSoundBuffer 

In C++: lpDSB->Release(); 

In C: IDirectSoundBuffer_Release( IpDSB ); 

} 
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access to everything that D irectSound can 
do. Once you have created this object, it 
can (among other things) create the 
DirectSoundBuffer object, which is the 

object that actually plays sounds (you 
knew that feature was in there some- 
where, right?). 

M ake sense? If not, don't sweat it- 
just remember that we have to create 
objects to do anything in D irectSound 
(and in any other DirectX APIs for that 
matter). 

DirectSound Objects 

T he DirectSound object is the key to using 
the D irectSound API. To create a Direct- 
Sound object of this type, you simply call 
the DirectSoundCreate function. Since this 
call is one of only two functions that 
aren't member functions of an object (the 
other is DirectSoundEnumerate), the calling 
sequence is the same for both C andC-H-: 

LPDIRECTSOUND IpDS; 

if (DirectSoundCreate(NULL, SflpDS, NULL) 
== DS.OK) 
// IpDS is nou a valid DirectSound 
object 

else 

// the DirectSoundCreate call 
faned (IfDS is NULL) 

The first NULL in the DirectSoundCre- 
ate call is the I D of the D irectSound 
device that you want to open— it will 
almost always be null. You can get a list 
of other valid IDs with the DirectSound- 
Enumerate function. T he second parameter 
is a pointer to where you'd like the 
D irectSound pointer to be placed (a 
pointer to an object pointer). The final 
parameter must always be null to keep 



COM happy. 

Once you have the DirectSound 
object, you can call any of the eleven 
member functions that it currently con- 
tains. H owever, there are really only three 
member functions that you will normally 
use: SetCooperativeLevel, CreateSound- 
Buffer, and Release. The Other member 
functions are for infrequent tasks like 
querying capabilities, compacting on- 
board sound memory, and managing 
speaker configuration. Don't worry about 
them— I've never had to use them and 
you probably won't either. 

Y ou must, on the other hand, use the 
SetCooperativeLevel member function. If 
you don't call it after creating your Direct- 
Sound object, most of the other member 
functions won't work. This silly goof has 
burned me at least once, and, judging by 
the C ompuServe message traffic, plenty of 
others. So, if you get a dserr.inualidparah 
result from one of the DirectSound func- 
tions, check your code and make sure you 
have set your co-op level. 

Since the SetCooperativeLevel call is 
our first member function, let's stop for a 
moment and discuss calling a C M 
member function from C -H- and C . A n 
example of a SetCooperativeLevel call in 
thetwo dialects is as follows: 

In C-H-: 

lpDS->SetCooperativeLevel 
( YourMainHund, DSSCLJORMAL ); 

In C: 

IDirectSound.SetCooperative Level ( 
IpDS, YourMainHund.DSSCL. NORMAL); 

You can see how C treats a 
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COM object just like a normal C ++ 
object— you call the function just like 
you would a normal C ++ member func- 
tion. In C, however, you must use 
macros to make calls to the member 
function. These macros serve to make 
the function calls cleaner and to mask 
any changes M icrosoft may make to 
COM in the future. 

All COM object macros follow 
the same naming convention: an upper- 
case "I ," the name of the object, an 
underscore, and, finally, the name of 
the member function that you wish to 
call. For example, a BillG COM object 
with a Boolean member function would 
have a macro called iBiiiG.isLoadedO 
that always returned TRUE. 

OK, back to SetCooperativeLevel— 
the first parameter (besides the object 
pointer itself) is a handle to your appli- 
cation's main window. W hy would 
D irectSound need an HWND? G ood ques- 
tion! M icrosoft considers sound a "sys- 
tem resource," so when a user flips 
away from your application. Direct- 



Listing 2. Tlie Locking Process 



Sound mutes all your sound! A Ithough 
this is correct behavior for most apps, I 
believe it should have been under our 
control— not the A Pi's. D irectSound 2 
is supposed to fix this lapse with sup- 
port for background sounds. 

Anyway (I'll make it through this 
function yet), the final parameter to 
SetCooperativeLevel is the priority level 
you are requesting. There are several 
different priority levels, but you will 
almost always use dsscl_normal, which 
signifies fully cooperative status (as 
opposed to grumpy, pain-in-the-ass 
status, I suppose). Actually, the other 
priority levels mostly create primary 
sound buffers, which you should rarely 
need to do. So, for our purposes, just 

USeDSSCL_NDRMAL. 

T he next function on my common 
list is CreateSoundBuffer. This function 
creates a DirectSoundBuffer object. W e 
will discuss these objects in the next 
section— they're where all the action is, 
so let's finish up the DirectSound object 
first. 



The final common DirectSound 
member function is Release. T his func- 
tion simply frees the DirectSound object. 
C all it at the end of your application to 
close DirectSound. You may notice that 
the Release function isn't shown in the 
DirectSound help file because Release 
is one of the standard COM member 
functions. It is there, though, and you 
should always call it when you're fin- 
ished with D irectSound. 

That wraps up the DirectSound 
object— doesn't do much, does it? It 
does, however, allow us to create 
DirectSoundBuffer objects, where the 
true coolness of D irectSound lies. 

DirectSoundBuffer Objects 

DirectSoundBuffer objects are containers 
for your actual audio data. They con- 
tain both the sound format (bit-depth, 
frequency, and so on) and a buffer for 
the sound data itself. T here are two 
types of DirectSoundBuffer objects: pri- 
mary and secondary. You will always 
create secondary buffers, unless you 
have a very unusual use for the primary 
buffer (I know of only one, which I'll 
talk about in a moment). 

Secondary buffers are nice because 
you can have many open at once. D ur- 
ing playback, each buffer is volume- 
scaled, pan-scaled, bit-depth adjusted, 
and mixed with other buffers complete- 
ly on the fly. After the final buffer is 
mixed, the resultant sound data is 
placed into the primary buffer to be 
heard. You don't have to worry about 
converting, massaging, or mixing any 
of the data— you just let D irectSound 
deal with it. Pretty cool! 

W hich, indirectly, brings us to the 
only reason to use primary buffers— 
because all secondary buffers are mixed 
into the primary buffer, it is the prima- 
ry buffer that governs the final sound 
quality. For example, if you play a 16- 
bit, 44 KHz secondary buffer, but the 
primary buffer is only 8-bit, 11 KHz, 
then your sound data will be scaled 
down to the primary buffer's format. 

So, if your sound card is capable, 
you can create a primary buffer and 
change its output format to deal with 
this problem. Usually though, the pri- 



HRESULT LoadSoundDatadPDIRECTSOUNDBUFFER IpDSB, char* SoundDataPtr, DWORD TotalBjtes) 
{ 

LPVOID ptrl,ptr2; 
DyORD lenl,len2; 
HRESULT result; 
TryLockAgainLabel: 

In C++: result = lpDSB->Lock( 0, TotalBytes, jiptrl, Silenl, &ptr2, JLLen2, ); 

In C: result = IDirectSoundBuffer.Lock( IpDSB, 0, TotalBytes, iptrl, aenl, «iptr2, !LLen2, 

0); 

switch (result) { 

case DS.OK: // The DirectSound buffer uas locked successfully 

memcpyC ptrl, SoundDataPtr ,lenl); 
if (ptr2) 

memcpyC ptr2, SoundDataPtr + lenl, len2); 
In C++: l|)DSB->UnLock( ptrl, lenl, ptr2, len2 ); 
In C: IDirectSoundBuffer.Unlocki IpDSB, ptrl, lenl, ptr2, len2 ); 
break; 

case DSERR.BUFFERLOST: // The DirectSound buffer was lost - try to restore 

In C++: result=lpDSB->Restore(); 
In C: result=IDirectSoundBuffer_Restore( IpDSB ); 

if (result == DS.OK ) // If the restore worked, go do the lock again 

goto TryLockAgainLabel; 
break; 

} 

returnC result ); 

} 
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mary buffer will be set in the best out- 
put mode for your particular sound 
card, so you'll never need to change it. 
Because of this fact, we'll focus on the 
more useful secondary buffers for the 
remainder of this article. If you really 
want to use the primary buffer and get 
stucl<, e-mail me, and I 'II try to help. 

So how do we create these awe- 
some secondary buffers? Well, the 
example function in Listing 1 does just 
that. 

The first thing this function does 
is set up a PCnWAVEFDRMAT Structure that 
contains the type of sound data the sec- 
ondary buffer will contain. Usually, you 
will simply load this structure from the 
header of a .WAV file. For a good 
example of loading and parsing .WAV 
files, checl< out an article titled, 
"Recording and Playing Waveform 
Audio" on M icrosoft Developer Net- 
work (M SDN ). 

N ext, the code sets up a dsbuffer- 
DESC structure that describes the 
requested secondary buffer. The 
duBufferBytes field specifies how large 
the secondary buffer should be in bytes. 
This amount is usually extracted from 
theDATA chunl< in a .WAV file. 

The second important field in the 
DSBUFFERDESC Structure is duFlags. In 
this case, we are setting duFiags to 
zero, but other useful options are DSB- 

CAPS.CTRLVOLUME, DSBCAPS.CTRLPAN, and 
DSBCAPS.CTRLFREQUENCY. These options 
tell DirectSound that you will be 
adjusting the volume, pan, or frequen- 
cy while the sound is playing. If you 
don't specify these options when you 
create the DirectSoundBuffer, then you 
won't be able to control these sound 
attributes at playbacl< time. 

T he code then asl<S the DirectSound 
object to go ahead and create a Direct- 
SoundBuffer object for us. If the function 
succeeds, the ipDSB variable will now 

contain our DirectSoundBuffer object 
pointer. As with the DirectSound object, 
once we're done with a DirectSound- 
Buffer, we must call the Release member 
function. 

N ow we l<now how to create a sec- 
ondary buffer, but how do we get our 
sound data into it? 



Loading Data into a 
DirectSoundBuffer 

To load sound data into our secondary 
buffer, we have to use the Lock, Unlock 
and Restore member functions. The 
locking process is a bit complicated, so 
let's start with an example function as 
shown in L isting 2. 

Geez, that's a lot of code just to 
load a buffer! It's pretty simple once 
we've walked through it though. 

The Lock function gives us access 
to the DirectSound buffers. I ts first para- 
meter is the Starting byte location of the 
lock you request— this will normally be 
zero unless you're streaming sound data 
into the sound buffer (we'll talk about 
this later). The next parameter is the 
number of bytes you are locking— this 
will almost always be the same amount 
that you used for the duBufferBytes field 
when you created the buffer. 

Two sets of pointers and lengths 
are filled in by the lock call. There are 
two sets of pointers and lengths because 
you could conceivably request a lock 
that wraps around the end of the sound 
buffer. If your lock parameters didn't 
cause DirectSound to wrap around its 
sound buffer, then ptr2 will be NULL. 
W ith these two pointers, you can use 
memcpy or meminove to place your sound 
data into the DirectSoundBuffer object. 

So far so good, but what does the 
other code do? W ell, one of the trickier 



Listing 3. Code to Play a DirectSoundBuffer 



parts of D irectSound is the fact that 
you can "lose" your sound buffer. Los- 
ing a sound buffer means that the buffer 
that was holding your sound data has 
been appropriated for other Direct- 
Sound needs. (Even stranger, on some 
new video-sound combination cards, 
you can also lose your sound buffers to 
D IrectD raw!) 

Losing a buffer is usually no big 
deal— you just call the Restore member 
function and reload the sound data into 
the buffer. You can implement various 
strategies to deal with this: reload the 
sound files back off the disk, keep the 
sound in another system RAM buffer 
so that you can reload it at any time, or, 
best of all, use streaming buffers (we'll 
talk about streaming a bit later). The 
sample code above simply calls the 
Restore function if the buffer was lost, 
and then retries the lock. 

Finally, after you've successfully 
locked the buffer and loaded your sound 
data, you must call the Unlock member 
function to give the buffer back to 
D irectSound. N otice that the Unlock 
function doesn't take pointers to the 
pointers and lengths (like Lock does), 
but accepts the pointers and lengths 
themselves. (T ry saying that three times 
quickly.) 

So, loading sound data isn't too 
bad at all. Just remember to have an 
easy way to reload it if your DirectSound 



DUORD status; 
TrjPlayAgainLabel: 
In C++: if ( lpDSB->Play( 0, 0, ) == DS.BUFFERLOST ) 
In C: if ( IDirectSoundBuffer.Play( IpDSB, 0, 0, ) == DSERR.BUFFERLOST ) 
if ( LoadSoundDataC IpDSB, SoundDataAddress, TotalSoundBytes ) == DS.OK ) 

goto TryPlayAgainLabel; // Try to play the buffer again 

GetAsyncKeyState(VK_ESCAPE); // Clear the state of the Escape key 

for (;;) { 
In C++: lpDSB->GetStatus(ktatus); 
In C: IDirectSoundBuffer.GetStatus (IpDSB, tetatus); 
if (status !=DSBSTATUS.PLAYING) 
break; 

if (GetAsyncKeyState(VK_ESCAPE)) // If the Escape key is hit, stop the sound 
In C++: lpDSB->Stop(); 
In C: IDirectSoundBuffer Stop( IpDSB ); 
} 
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Listing 4. A Streaming Example tliat can be Pasted into a DirectSound Application 



// This field will be non-zero while sound is streaming 

// Set this field to stop sound streaming 

// The next sound address that uHl be mixed into the DS 

// How many bytes are left from CurrentPosition 
// When this is non-zero the timer callback won't execute 
// The size of half the DirectSound buffer (don't change) 
// The pointer to the last half buffer that we were in 



typedef struct DSSTREAMTUG { 

int Playing; 

int PleaseCLose; 

char* CurrentPosition; 
buffer 

BytesLeft; 
NoCallbacks; 
HalfBufferPoint; 
LastHalf; 
(don't change) 

int CLoseOnNext; // Internal flag to mark the end of playback (don't change) 

LPDIRECTSOUNDBUFFER IpDSB; // The DirectSound buffer that is handling the streaming 
char SHenceByte; // The value for silence (different for 8 and 16 bit sounds) 

} DSSTREAH; 

static void StreamCopy(DSSTREAH* s, char* ptr, DWORD len) // Copy from buffer into DS with 

end of buffer handling 

{ 

DWORD amt; 

amt=(len>s->BytesLeft)?s->BytesLeft:len; // Only copy what's left in the main sound 
buffer 
if (amt) { 

memcpy (ptr , s->CurrentPosition , amt) ; 

s->CurrentPosition+=amt; 

s->BytesLeft-=amt; 

} 

len-=amt; 

if (len) { // Fill the remainder of the buffer with silence 

memset(ptr+amt,s->SilenceByte,len); 

s->CloseOnNext=l; // Set the "done on the next buffer switch" flag 

} 

} 

static void StreamFillAHalf(DSSTREAM* s, DWORD half) // fill a half of the DirectSound 

buffer 

{ 

char* ptrl; 
char* ptr2; 
DWORD lenl, len2; 

TryLockAgainLabel: 

switch (s->lpDSB->Lock(half, s->HalfBufferPoint, jiptrl, flenl, &ptr2, «LLen2, 0)) { 
case DS.OK: 

StreamCopy(s, ptrl, lenl); // Copy sound data into the first pointer 

if {ptr2) // Copy sound data into the second pointer if necessary 

StreamCopy(s, ptr2, len2); 
s->lpDSB->Unlock(ptrl, lenl, ptr2, len2); 
break; 

case DSERR.BUFFERLOST: // The DirectSound buffer was lost - try to restore 

if (s->lpDSB->Restore() == DS.OK) 

goto TryLockAgainLabel; 
break; 

} 

} 

static void CALLBACK StreamTimer(UINT id, UINT msg, 
{ 

playp,writep; 



user. 



dwl, DWORD dw2) 



buffer is ever lost. I try to make a stand- 
alone function that I can call from any- 
where in my application if my buffer 
disappears. 

N ow that we have sound data in 
our DirectSoundBuffer object, we're 
ready to play it! 

Simple DirectSoundBuffer 
Playbacic 

I n comparison to the set up and loading 
of the DirectSoundBuffer object, play- 
back is a piece of cake. The two play- 
back control member functions are Play 
and Stop, and they do exactly what 
you'd guess. As an example, let's look at 
the code in L isting 3 which plays a 
DirectSoundBuffer until you press Escape. 

T he Play member function actually 
starts the sound. It takes three parame- 
ters—the first two are reserved and 
must be zero. The final parameter is a 
flag field. C urrently, the only flag is 
DSBPLAY.LOOPING which tells D irectSound 
to keep looping the DirectSoundBuffer 
object over and over. The DSBPLAY.LOOP- 
ING flag is also used to set up a stream- 
ing sounds. 

N otice that, again, you have to 
watch for the sound buffer being lost. If 
the buffer is lost, then this code simply 
calls the LoadSoundData function that you 
wrote earlier. This is a workable but 
clumsy solution, because you have to 
buffer the sound data twice— once in 
your own buffer and once inside the 
DirectSoundBuffer object. Alternatively, 
you could load the sound data off the 
disk to save the double memory use. 
However, as I alluded to earlier, the 
best solution is probably to stream the 
sound data. 

OK, so once the sample begins 
playing, the above code simply waits 
until the GetStatus member function 
tells us that the DirectSoundBuffer object 
is finished. This will happen if the 
DirectSoundBuffer plays through to the 
end of the sample, or you hit the Escape 
key and cause the Stop member function 
to be called. 

There are other member functions 
for controlling the volume, pan, fre- 
quency, and playback position of the 
DirectSoundBuffer object, but these are 
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all pretty self-explanatory so 1 11 let you 
experiment with them on your own. 

And that's all there is to simple 
playback. No problem, right? Good, 
because our final discussion will be 
about streaming audio. It is a bit more 
complicated, but definitely worth 
understanding. 

DirectSound Streaming 

Sound streaming is the act of using a 
tiny buffer to play a large sample a little 
bit at a time. Streaming is generally 
used to play sound data off a hard drive 
or CD-ROM , but you can also use it to 
play a large piece of sound data into a 
tiny DirectSound buffer. 

This is how you get around the 
lost buffer problem— you load an entire 
sample into system memory and then 
use D irectSound to play a little bit at a 
time. In this situation, if you lose the 
sound buffer, it's no big deal because 
you are not losing the entire sample- 
just a little piece. 

As you can imagine, playing sound 
data this way is more complicated than 
just calling the Play member function. 
T he nice thing is that this technique 
can be encapsulated into one function 
call fairly easily, so you can just use the 
same code over and over again. 

Basically, DirectSound streaming 
is accomplished by creating a looping 
secondary buffer and placing data into 
it at the right time. DirectSound 
believes that it is playing the same 
sound over and over, but actually we're 
placing new sound data into the buffer 
each time it loops around to simulate 
one long seamless sound. 

The easiest way to learn streaming 
is to start with an example that can be 
pasted right into a DirectSound appli- 
cation to implement streaming immedi- 
ately. This example will play a sound 
sample that is loaded into system 
RA M , but you could easily modify it to 
play sound off a hard drive or CD- 
ROM . Let's check it out in Listing 4 
(only the C -H- calls are shown to make 
the code easier to read). 

To start streaming with this exam- 
ple code, call the StartStreaming func- 
tion with a stream structure, the sound 
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DyORD uhichhalf; 

DSSTREAH* s={DSSTREA[1*)user; 

if (s->NoCaUbacks++==0) { 

if {s->PleaseCLose) { // Programmer requested Close - shutdown ijiiinediately 

ShutDounStreamingLabel: 
timeKillEventUd); 
tiiiieEndPeriod{62); 
s->lpDSB->Stop(); 
s->lpDSB->Release{); 
s->Playing=0; 
return; 

} 

s->lpDSB->GetCurrentPosition(4playp,fturitep); // Get the current position and figure 
the current half 

uhichhalf=(playp < s->HalfBufferPoint)?0:s->HalfBufferPoint; 
if (uhichhalf != s->LastHalf) { 
if {s->CLoseOnNext) // If we previously used up our sound data, then do a 

shutdown 

goto ShutDownStreamingLabel; 

StreamFILLAHalfCs, s->LastHalf ) ; // FILL the buffer half that we just left 
s->LastHalf =whichhalf ; 

} 

} 

s->NoCallbacks~; 

} 

void StartStreaiiiing(DSSTREIin* s, void* addr, DWORD len, LPDIRECTSOUND IpDS, LPWAVEFORNIITEX 

format) 

{ 

DSBUFFERDESC dsbd; 
if (s) { 

memset(s,0,sizeof{DSSTREA[1)); 

if {(addr) Mi (IpDS) Mi (format)) { 

memset( jidsbd, 0, sizeof(dsbd) ); 

dsbd.lpwfxForinat=format; 

dsbd. dwSize=sizeof (DSBUFFERDESC) ; 

dsbd.dwBufferBytes= ((forinat->nllvgBytesPerSec/4)+2047)r2047; 
dsbd.dwFlags=0; 

if (lpDS->CreateSoundBuffer( idsbd, k->lpDSB, 0) != DS.OK) 
return; 

s->NoCallbacks=l ; // Don't let the callback do anything until we're fully setup 
timeBeginPeriodC 62 ); 

if (timeSetEvent( 62, 0, StreamTimer, (DyORD)s, nHE.PERIODIC )==0) { 

tiineEndPeriod( 62 ); 

s->lpDSB->Release(); 
} else { 

s->Half Buf f erPoint=dsbd . dwBuf f erBytes/2 ; 
s->CurrentPosition=addr ; 
s->BytesLeft=len; 

s->SiLenceByte= {forinat->wBitsPerSample==16) ? 0:128; 
StreamFiLLAHalf(s, 0); 
StreamFILLAHalf (s, s->HalfBufferPoint) ; 
s->Q.oseOnNext=0; // dear the close flag, so that the first two buffers are 

played 

s->lpDSB->Play( 0, 0, DSBPLAY.LOOPING ); 
s->NoCallbacks=0; 

} 
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Listing 4. Continued from p. 45 



} 

} 

} 

// Streaming test code: 
volatile DSSTREAM s; 

StartStreamingC {DSSTREA[1*)k, SoundDataAddress, TotalSoundBytes, IpDS, iSoundFormat ); 
GetAsjncKeyState{VK_ESCAPE) ; // dear the state of the escape kej 
uhUe (s. Playing) { // wait until the sound is done or the user hits escape 

if {GetAsyncKejState(VK.ESCIIPE)) 
s.PleaseClose=l; 

} 



data address, the sound data length, the 
DirectSound object to use, and the for- 
mat of the sound data. From there, 
everything is handled automatically, 
and sound will start immediately. 

If you'd lil<eto stop the streaming, 
just set the PleaseStop field to non-zero. 
You can monitor the playback with the 
Playing field: non-zero means that the 
stream is still playing, and zero means 
that the stream has been stopped and its 
resources have been freed. Finally, to 
track the playback position, usetheCur- 
rentPosition field (it is a pointer that 
increases from your starting address as 
playback proceeds). 

Now let's shift from describing how 
to use the streaming example to how it 
actually works. We'll begin with the 
Sta rtStreaming f U n Cti n . 

The StartStreaitiing function only 
has to set the appropriate values in the 
DSSTREAM Structure and start up the 
timer callback. First it creates a small 
DirectSoundBuffer that will handle one- 
fourth of a second of audio data. It 
then sets a timer to call the streamTimer 
function and assigns all of the initial 
streaming values. Then the StreamTimer 
function will be called 16 times per sec- 
ond (every 62 milliseconds) to process 
all of the sound data. 

The StreamTimer callback contains 
most of the logic for streaming. The 
first thing it does is to check to see if the 
PleaseQose flag is set; if so, it closes the 
streaming for this sound. N ext, the 
timer checks where the current play 

position is with the GetCurrentPosition 
member function. If DirectSound has 



moved from one half buffer to the next, 
then the old half buffer is ready for new 
sound data. 

T he StreamFillAHalf function is 
used to load sound data into one half of 
the DirectSound buffer. It handles the 
locking, restoring, and unlocking of the 
DirectSoundBuffer object. The Direct- 
SoundBuffer object, in turn, calls the 
StreamCopy function to move the data 
from your large sound buffer into the 
tiny DirectSound buffer. 

One bit of semi-tricky logic is 
found when the StreamCopy function 
determines that the end of your sound 
data has been reached. StreamCopy can't 
just close the stream immediately, 
because you wouldn't hear the last little 
bit of sound, so it sets a flag called 
cioseOnNext. T his flag is checked on the 

next buffer switch in the StreamTimer 

function which lets you hear the last 
buffer's worth of sound. 

This example code is rather sim- 
ple—integrating it into your own appli- 
cation should be a snap. A few cool fea- 
tures to tack on: the ability to pause the 
playback, a smarter callback that handles 
multiple streams (instead of one callback 
per stream), and the ability to stream 
from a disk file. Go crazy with it— after 
all, you have the source code! 

This is Not a Summary 

W ell, you made it! You now know 
almost everything there isto know about 
D irectSound. 

After you've used it a while, I 
think you'll agree that M icrosoft really 
did a great job on D irectSound: it is a 



terrific, low- level API to play digital 
sound with little to no latency response. 
As this article demonstrates, however, 
D irectSound is not a high-level API . A 
DirectSound application must handle 
buffer management, callbacks, stream- 
ing, start and stop control, and such on 
its own behalf. 

For those who don't want to deal 
with the low-level coding that Direct- 
Sound requires, there are several good 
libraries that combine D irectSound's 
awesome playback abilities with a true 
application-level API to give you the 
best of both worlds. 

Personally, I think the best thing 
about D irectSound is that my com- 
plaints about the old days of W indows 
programming are getting better and 
better. 

"Back when I was a W indows pro- 
grammer, we had to walk to work in 
two feet of snow every morning, and 
hexadecimal hadn't been invented yet, 
and we didn't have DirectSound, and 
my mouse was a real dead mouse with 
wires shoved up its ■ 



Jeff Roberts is a programmer at RAD 
Software, publisher of Smacker and the 
M lies Sound System. H e can be reached 
via email at gdmag@mfi.a)m. 



DirectSound for the Impatient 



Ror those of you who don't 
want to read this whole arti- 
cle, just follow the following 
easy steps to add Direct- 
Sound to your application in no time: 

1. Create a DirectSound object. 

2. Set the cooperative level to 

DSSCL.NORHAL. 

3. Create a secondary sound buffer. 

4. Lock the sound buffer. 

5. Fill the buffer with your sound data 
using the two pointers and lengths 
returned by Lock. 

6. Unlock the sound buffer. 

7. Play the sound buffer. 

8. Release the sound buffer. 

9. Release the DirectSound object. 
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Playing 
wit:li Waves 



You've just blown away a 
room full of bad guys. You 
then hear a door open and a 
squad of gurgling demons 
behind you. A breeze carries 
snatches of tinny post- apoc- 
alyptic singing forced 
through a wheezing old FM 
radio. "The population is greatly 
decreased... " You head toward it, hop- 
ing to find a friend. 

There's no substitute for the plea- 
sure audio gaming experiences bring to 
players' ears. W ithout sound, games lack 
essential life-saving audio cues, humor, 
character, and magic. I 've spent much 
time discussing cross- platform graphics 
and user interaction, and it's about time 
I rounded things off with a bit of audio. 

In this article, I will leave you with 
a short demo that runs without change 
on top of a small core of W indows- 
and M acintosh-specific code. You will 
see how to implement a simple Play- 
W ave function that will allow up to 
four simultaneous sounds to play using 
system services, in this case the M acin- 
tosh Sound M anager and W indows' 
D irectSound. 



Basic Wave Theory 

T he algorithm for mixing two waves isn't 
very difficult. Sound waves are additive: 
two waves played at the same time pro- 
duce a combined wave that is their sum, 
as approximated in Figure 1. T he goal of 
a software mixer is to allow a single wave 
synthesizer to play multiple waves simul- 
taneously, so its job is to perform the 
addition itself before playing the com- 
bined wave, instead of leaving the job to 
natural physics. 

Electronic sound devices usually 
play digitally sampled waves. A digital 
description of a sound wave is created by 
recording the amplitude of a wave input 
at a constant frequency using a specific 
number of bits to measure the wave at 
each time slice Today's hardware gener- 
ally handles 8 or 16 bits per sample at 
frequencies of 11,025, 22,050, or 44,100 
samples per second, with higher frequen- 
cies and resolution producing a more 
accurate replica of the original while 
requiring additional memory and pro- 
cessing power. 

A one-second, 8- bit wave sampled 
at 11,025 hertz is represented by a block 
of 11,025 bytes, each of which describes 



the amplitude of the wave at a specific 
point in time with a number from -127 
to 128. To mix two such waves into a 
third buffer, the mixer steps through 
each wave's 11,025 samples and adds 
them together, storing the result in a 
third 11,025- byte block to be played out 
through the speaker. T his is the elemen- 
tal mixing operation: adding two waves. 

You can perform other operations 
on sampled sound data to produce special 
effects. You can change the volume of a 
sound by multiplying or dividing every 
sampled value by a constant. You can 
fade a sound by dividing each sample 
value by a number that increases or 
decreases across the wave Y ou can create 
an echo by mixing a wave with itself with 
a slight delay. You can play waves back- 
wards, slow them down, distort them, or 
do whatever mathematical transforma- 
tionsyou like. 

Usually, a game has simple run-time 
needs: it has to mix waves with different 
starting and ending times into a single 
continuous audio stream. W hen you fire 
two shots in quick succession, you want 
to hear the second even though the first 
has started playing, and you still want 
any active background music or other 
noises to play through. 

Generally, a game doesn't have the 
luxury of mixing the two waves together 
before playing them as one combined 
wave because they don't start or end at 
predefined times. Someone has to mix 
new sounds into an active audio stream 
by mixing in the new wave starting just 
after the point from which the sound 
hardware is playing. 

There are other things a mixer has 
to worry about, too. For instance, the 



















Figure 1. Two waves playing simultaneously, approximately. 
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mixer doesn't have infinite memory at its 
disposal, so an application may asl< to 
play a sound that's too large to fit in the 
buffer the mixer is using, so the mixer 
may have to break the sound into pieces. 
Or maybe the application wants to mix 
two waves sampled at different rates or 
with different resolutions. A general pur- 
pose mixer has to convert them to a com- 
mon format. 

Books have been written on the 
subject of signal processing, and numer- 
ous software mixers and sound editing 
tools abound. You can dig into them, but 
I have neither the space, the time, nor the 
expertise to write another volume on 
sampling theory. As long as you under- 
stand the basics of what your wave mixer 
does, you don't have to deal with the 
gritty details. Unlessyou wantto. 

Pitfalls 

Both DirectSound and Sound M anager 
cope with playing whatever sound in 
whatever format of whatever length you 
throw at them. You can take their abili- 
ties for granted. H owever, it's important 
to understand the basics of wave mixing 
in order to understand a fundamental 
performance difference between the two. 

Programmers who write wave mix- 
ers must inevitably answer the following 
question: W hat happens when the sum 
of any two samples from the waves to be 
mixed exceeds the resolution of the sam- 
ple? H ow do you mix two 8- bit samples 
when their sum is greater than 128 or less 
than -127? A byte simply can't handle 
that information. Digital technology has 
let you down. 

At this point, you have two basic 
choices. You can divide every sample in 



half, essentially restricting each wave to 
the -63 to -f64 range to guarantee the 
sum to fall between -127 and 128, or 
you can continue as usual, replacing any 
sum greater than 128 with 128 and less 
than -127 with -127. I suppose you can 
always ignore the problem, too, but I 
don't recommend that option. 

W e know already that dividing sam- 
ples in a wave by a constant (in this case 
2) lowers the volume of the wave. So 
basically, the first technique is to turn 
down every wave to be mixed so that 
they're guaranteed never to exceed the 
maximum volume. You divide each sam- 
ple by the number of waves played before 
adding them together. T hat's the same as 
adding them all together and dividing by 
the number, so I call this averaging the 
waves. I'm going to break my impartial 
reporter front for a second to say that this 
is the wrong way to mix waves for games! 

The second technique guarantees 
that the waves you play will always be 
played at the expected volume, but if the 
sum of all the waves played exceeds the 
limits of the digital representation, the 
highs and lows will get chopped off. If 
you know you're going to be mixing four 
sounds, you may choose to author your 
sounds in a reduced range so they never 
distort, but that's up to you. T his mixing 
technique is called clipping the waves 
because it clips off the highs and lows. 

F igure 2 shows these two mixing 
methods at work. L ooking at these dia- 
grams, you can see how averaging dis- 
torts the shape of the wave, squashing it 
into silence. W hen you've only got 
eight bits to describe a sound sample, 
you don't want to throw any of them 
away by division! On the other hand. 
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J on Blossom 

OrectSound and 
Sound Manager handle 
the process 
of mixing audio 
differently, Knowing 
each platform 
will prevent your 
game's sounds from 
unexpected clipping 
as well as 
average to low 
volumes, 
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AUDIO 




Listing 1. PlayWave for tlie IVIacintosli 






ChannelHeader[ChannelToUse] .length = SampleSize; 


Global channel information initialized by BeginSound 




ChannelHeader[ChannelToUse].loopStart = SampleSize; 


SoundHeader ChannelHeader[4]; 




ChannelHeader[ChannelToUse].loopEnd = SampleSize; 


SndChannelPtr pChannel[4] ; 




// aiov only 11025Hz samples 


void Playyaiie(int SampleSize, int SampleRate, 




// This is just to save space. The code on 


short BitsPerSample, short ChannelCount, 




// ftp.mfi.com allows 22050 and 44100 as well 


char unsigned* pSample) 




ChannelHeader [ChannelToUse]. sampleRate = ratell025hz; 


{ 




ChannelHeader [ChannelToUse]. baseFrequency = ratell025hz; 


// Look for a channel to use to play this sample 




// AUow only 8-bit samples 


int ChannelToUse = -1; 




// Again, see the code on the ftp site 


for (int Count = 0; Count < 4; ++Count) 




// The stdSH code indicates 8-bit samples 


{ 




ChannelHeader [ChannelToUse]. encode = stdSH; 


// An available channel is 




// Set up the sound data to indicate 


// recognized by a null sample pointer 




// that the channel is playing 


if (pChannel[Count] Ml !Channellleader[Count].samplePtr) 




ChannelHeader [ChannelToUse] .samplePtr = 


{ 




(char*)pSample; 


Lnanneiiouse - Louni, 




// riay tne sounoi 


break; 




SndCommand Command; 


} 




Command.cmd = bufferCmd; 


} 




Command. paraml = 0; 


if (ChannelToUse > -1) 




Command. param2 = (long)4ChannelHeader [ChannelToUse]; 


{ 




SndDoCommand(pChannel[ChannelToUse], iCommand, false); 


// Found an unused channel... 




// ljueue up a callback to reset the channel 


// Set up buffer information 




// header when finished. The command gets passed 
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Listing 1. Continued from p. 50 



// as an argument to the callback function. 
// In this case, parain2 will contain a pointer to 
// the memory to be zeroed when the wai/e terminates. 
Command.cmd = callBackCmd; 
Command. paraml = 0; 
Command. param2 = 
{long)4ChannelHeader[ChannelToUse].samplePtr; 

SndDoCommand(pChannel[ChannelToUse], Kommand, false); 

} 

} 

pascal void SoundCallBack(SndChannelPtr pChannel, SndCommand* 
pCommand) 
{ 

// This function gets called when ue queue up a 
// callBackCmd above, to indicate that the sample 
// has finished playing. 
// 

// The command's param2 points to the 
// ChannelHeader.samplePtr of the channel that finished, 
// which we zero to indicate that it is no longer playing. 
*((Ptr*)pCommand->param2) = 0; 



clipping can distort tine tips of ttiewave, 
creating harsh highs and lows lil<e the 
ones you might hear escaping speal<ers 
that have been pushed to a volume they 
can't support. 

For reasons I can neither explain nor 
imagine, Apple decided that Sound 
M anager should average waves, even if 
mixing them normally wouldn't cause 
clipping. T his guarantees you will never 
hear clipping from waves Sound M anag- 
er produces, but it also guarantees that 
individual sounds drop in volume as 
other sounds begin to play. 

D irectSound clips waves that exceed 
the playback resolution. This guarantees 
that your sounds will be played at full 
volume, but it also leaves your sounds 
susceptibleto clipping. 



communication pipes 
to the Sound M anag- 
er. T hey're essentially 
queues of commands 
to be processed, 
including commands 
to play a buffer from 
memory, loop over a 
specific piece of a 
sample, or perform 
other simple sound 
operations. 

To play a sam- 
ple from memory, we 
have to set up a chan- 
nel, initialize a 
bufferCmd command 
that points to the 
wave data to be 
played, and call Snd- 
DoCommand to pass the 
command down the 
pipe. By following 
that with a callBackCmd, we can have the 
Sound M anager call us back when it's 



finished playing the sample. 

That's all it takes. Every time you 
send a bufferCmd, the Sound M anager 
mixes all the active sounds into one audio 
stream and plays it out the speaker. 

For our purposes, we'll allow four 
sounds to be played at once. T he Begin- 
Sound function creates four sound chan- 
nels using SndNeuChannel, registering the 
SoundCallBack function as the target of a 
callBackCmd command for that channel. It 
initializes a SoundHeader Structure to 
describe the sound wave installed in each 
channel. Each header initially contains 
null asthe pointer to its sound, indicating 
the channel is unused. EndSound cleans up 
this work when we're done playing. 

The PlayWave function, shown in 
L isting 1, implements the heart of the 
system. It searches the four channels to 
find an unused one, as indicated by a 
ChannelHeader whose sample pointer is 
null. If it can't find one, it refuses to play. 

If it does find a free channel, Play- 
Wave fills in the associated ChannelHeader 



Playing the Mac 

N ow we're going to make some noise, 
starting with the M acintosh. Two plat- 
forms worth of code is too much to fit in 
one article, so I 've only printed the high- 
lights here. Check out the Game De/elop- 
er web site for the full source code. 

In spite of my exhortation against 
mixing waves by averaging (shudder), I 'm 
going to show you a simple way to use 
the Sound M anager. 

Sound C hannels are the essential 
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Listing 2. PlayWave for DirectSound 



// Global channel information initialized 
// by BeginSound 

static LPDIRECTSOUNDBUFFER pChannelM; 

static LPDIRECTSOUND pDirectSound = 0; 

void Playyaiie(int SampleSize, int SampleRate, 

short BitsPerSample, short ChannelCount, 

char unsigned* pSample) 

{ 

// Look for a channel to use to plaj this sample 

int ChannelToUse = -1; 

for (int Count = 0; Count < 4; ++Count) 

{ 

if (!pChannel[Count]) 
{ 

// This channel isn't in use 
ChannelToUse = Count; 
break; 

} 

else 
{ 

DWORD Status; 
HRESULT DSResult = 

pChannel[Count] ->GetStatus (iStatus) ; 
if (DSResult == DS.OK M 

! (Status 4 

(DSBSTATUS.PUYING | DSBSTATUS.LOOPING))) 



{ 



// This channel has finished playing - 
// it's OK to free it and use it now 
pChannel[Count]->Release() ; 
pChannel[Count] = 0; 
ChannelToUse = Count; 
break; 



} 



} 

if (ChannelToUse > -1) 
{ 

// Found an unused channel... 



// Set up buffer information 
UAVEFQRHATEX yai/eFormat; 
WaveFormat.wFormatTag = WAVE.FORMAT.PCM; 
UaweFormat.nChannels = ChannelCount; 
UaveFormat.nSamplesPerSec = SampleRate; 
UaveFormat.wBitsPerSample = BitsPerSample; 
UaveFormat.cbSize = 0; 

WaveFormat.nBlockAlign = Uai/eFormat.nChannels * 

(Wai/eFormat.uBitsPerSample / 8); 
UaveFormat.nAi/gBytesPerSec = Uai/eFormat.nBlockAlign * 

UaweFormat.nSamplesPerSec; 
// Set up a DirectSound buffer 
DSBUFFERDESC BufferDesc; 
ZeroMemory (!iBuf f erDesc , sizeof (Buf f erDesc) ) ; 
BufferDesc. duSize = sizeof (BufferDesc); 
BufferDesc.duFlags = DSBCAPS.STAHC I DSBCAPS.CTRLDEFAULT; 
BufferDesc. duBufferBytes = SampleSize; 
Buff erDesc. IpwfxFormat = MaveFormat; 
// Create a new buffer using the settings for this wai/e 
HRESULT DSReturn = 

pDirectSound->CreateSoundBuffer(SiBufferDesc, 
&pChannel[ChannelToUse] , 0) ; 
if (DSReturn == DS OK Sift pChannel[ChannelToUse]) 
{ 

// Lock the buffer and copy in the data 
BYTE* pData; 
DWORD DataSize; 

if (pChannel[ChannelToUse]->Lock(0, SampleSize, 
ipData, jiDataSize, 0, 0, 0) == DS.OK) 

{ 

memcpy(pData, pSample, SampleSize); 
// Unlock the buffer 
pChannel[ChannelToUse]->Unlock(pData, 

DataSize, 0, 0); 
// Actually play it! 
pChannel[ChannelToUse]->Play(0, 0, 0); 



with the sample characteristics, points it 
at the specified wave data, and sends a 
bufferCmd command to the appropriate 
channel to start the wave playing. I n the 
listing, I've restricted PlayWave to 8-bit 
11,025H z samples, but the code avail- 
able on the G ame D ev eloper web site 
allows for others. 

Before leaving, PlayWave queues up 
a callBackCmd command, which will 
result in a call to SoundCallBack when the 
wave has finished playing. SoundCallBack 
zeroes the sample pointer in the appro- 
priate ChannelHeader, making the channel 
once again eligibleto play a wave. 



The Well-Tempered PC 

The Sound M anager requires you to cre- 
ate channels only for the sounds you want 
to mix, implying a specific playbacl< buffer 
into which all channels are mixed. But 
DirectSound has no such default. A pri- 
mary buffer represents the sound moving 
through the hardware, and the application 
must create a primary buffer before it can 
play any sound through the hardware. 

TheW indows BeginSound implemen- 
tation handles the set-up of the primary 
buffer. Because a primary DirectSound 
buffer must be associated with a window, 
BeginSound creates a simple static text con- 



trol and sets up DirectSound for exclusive 
audio access through that window before 
creating the primary sound buffer. End- 
Sound reverses all that and frees the addi- 
tional buffers created in the process of 
playing waves 

nee the system is set up, the W in- 
dows PlayWave implementation follows a 
pattern similar to the one described for 
Sound M anager. Specifically, it looks for 
an unused channel among the four 
allowed, creates and sets up a buffer for 
the requested sample, and calls Play. 

Listing 2 shows the source code for 
this function. N otice that every call to 
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Method 2: Clipping (DirectSound) 



PlayWave creates a new D irectSound buffer 
to hold the wave you're playing. D irect- 
Sound doesn't play waves directly from 
memory lil<e Sound M anager does, so 
PiayWave has to lock the buffer, copy in the 
wave data, and unlock it. That may be 
time-consuming and may even involve 
downloading a wave to the sound hard- 
ware. A better system could avoid that by 
keeping waves to be played in preallocated 
and precopied DirectSound buffers. 

The Echo Chamber 

I've included a demo that uses the stan- 
dard C file package to open a file called 
sample.wav, assumed to be in the .WAV 
file format used by W indows and read in 
sampled wave data. Then, it calls Play- 
W ave eight times with that data, leaving 
^/4 of a second between each call, waits 
another five seconds, and terminates. 

Since .WAV is a PC format, con- 
taining data in Intel byte ordering, the 
demo uses two functions to adjust them to 



Figure 2. Two mixing methods.: 



the run-time format. I've declared Suapl6 
and Suap32, which swap bytes into 
M otorola format on a M ac and leave bytes 
intact on a PC. For a 16-bit sample, every 
16 bits of the wave data will have to be 
swapped around as well, a factor that 



made me decide to leave this demo in 8- 
bit land. 

I urge you to compile and run these 
on a M ac and on W indows 95 if you can. 
You'll immediately hear the difference 
between avaaged and clipped mixing. The 



mtfyj /www.gdmag.com 



GAME DEVELOPER - J UNE/JULY 1995 55 



AUDIO. 



Listing 3. Code to Play a Wave Eiglit Times 



// The siiriple Ua«e Mixing API 
int BeginSound(«oid); 
void EndSound(void); 

void PlayUave(int SairipleSize, int SaupleRate, 

short BitsPerSample, short ChannelCount, 

char unsigned* pSample); 

// Byte-suapping functions 

short unsigned Suapl6(short unsigned value) ; 

long unsigned Suap32(long unsigned value); 

// The deuo 

void DeinoBain(void) 

{ 

int SampleSize =0; 
int SampleRate =0; 
short BitsPerSample =0; 
short ChannelCount =0; 
char unsigned* pSairiple =0; 
// Load a wave file 

FILE* pFHe = fopenC'sairple.uav", "rb"); 

if (pFiLe) 

{ 

// We're just going to assume this file is valid 

// Skip the 'RIFF' tag and fiLe size (8 bytes) 

// Skip the 'HVE' tag (4 bytes) 

fseek(pFne, 12, SEEK.SET); 

// Now read RIFF tags until the end of file 

unsigned long Tag; 

unsigned long Size; 

whae (!feof(pFae)) 

{ 

// Read, Hatching for file end 

if (fread((char*)!iTag, 1, 4, pFile) == 0) 

break; 
Tag = Swap32(Tag) ; 
fread((char*)!iSize, 1, 4, pFiLe); 
Size = Swap32(Size); 

if (Tag == 0x20746066) // The 'fmt ' tag 
{ 

// 16-bit PCH flag - assume PCM format 
fseek(pFile, 2, SEEK.CUR); 
// 16-bit Channel Count 
fread((char*)4ChannelCount, 1, 2, pFile); 
ChannelCount = Swapl6(ChannelCount) ; 
// 32-bit Sample Rate 
fread((char*)4SampleRate, 1, 4, pFile); 
SampleRate = Swap32(SampleRate) ; 
// Skip Average bytes per second - (4 bytes) 
// Skip padding - (2 bytes) 
fseek(pFne, 6, SEEK.CUR); 
// 16-bit Bits Per Sample 



fread((char*)SiBitsPerSample, 1, 2, pFile); 
BitsPerSample = Swapl6(BitsPerSample) ; 
// Skip uhatever's left 
if (Size > 16) 

fseek(pFae, Size - 16, SEEK CUR); 

} 

else if (Tag == 0x61746164) // The 'data' tag 
{ 

// Allocate space and read in the wave 
pSample = (char unsigned*)malloc(Size) ; 
if (pSample) 
{ 

SampleSize = Size; 

fread((char*)pSample, 1, Size, pFile); 

} 

} 

else 
{ 

// An unknown tag - just skip it 
fseek(pFae, Size, SEEK CUR); 

} 

} 

fclose(pFile); 

} 

// Now play the wave! 

if (pSample ti& BeginSoundO) 

{ 

long unsigned Time; 

// (Attempt to) play 8 times 

int PlayCount = 0; 

uhiLe(PlayCount < 8) 

{ 

PlajUave(SampleSize, SampleRate, BitsPerSample, 

ChannelCount, pSample); 
++PlayCount; 

// klait 3/4 of a second between plays 

Time = GetHiUisecondTimeO; 

while (GetHiUisecondTimeO - Time < 750) 

} 

// Wait S seconds then quit 
Time = GetBillisecondTimeO ; 
while (GetBillisecondTimeO - Tijiie < 5000) 

EndSoundO; 

} 

// Qean up 
if (pSample) 
free(pSample); 

} 



Sound M anager makes the demo sound 
like an echo chamber, repeating the wave 
over and over at progressively lower vol- 
umes while the D irectSound demo pro- 
vides eight crisp new shots Try increasing 
the number of channels allowed to 8, swap 
in a loud wave, and listen as all your 
sounds are reduced to one-eighth their 



original volume by the Sound M anager 
and clipped to distortion by D irectSound. 

T here are ways to combat the Sound 
M anager's dynamic volume adjustments. 
You can guarantee that four sounds will 
always be playing by forcing the unused 
channels to loop over a buffer full of 
zeroes. You can artificially turn up the vol- 



ume on the channels as new waves are 
mixed in. r you can write your own 
mixer that plays through a single Sound 
M anager channel, but I won't be held 
responsiblefor the results! ■ 

Jon Blossom can be reached through 
GameD a/ eloper magazine 
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Each of us interprets differently 
what we read, so that even the 
author cannot really know what 
pictures his or her words might 
paint in the reader's mind. T his 
is a wondrous, pseudo- magical 
thing about the written word as 
a means of creative expression. 
It's also the reason a written script gener- 
ally proves insufficient as a tool for cine- 
matographers, animators, and game 
developers, who are working largely with 
graphical concepts W hen the visual ele- 
ment is this important to the end result, 
it is crucial that everyone involved has the 
same picture in mind. In most cases, the 
script remains a necessity, but the very 
flexibility that leaves its phrases open to 
personal interpretation makes text too 
inexact for the planning and sharing of 
visual concepts. This is where the story- 
board comes into play. 

I n case any reader is unfamiliar with 
the term, a storyboard is a graphical rein- 
terpretation of the script, using a series of 
rough sketches to convey setting and 
action from scene to scene, sometimes 
even from one movement to the next. 
Filmmakers and animators have used 
these visual devices for decades. As digi- 
tal graphics grow in sophistication and 
importance, developers too rely increas- 
ingly on this tool to communicate and 
plan a game's visual element. 

In general, the storyboard is a visu- 
alization aid. 1 1 helps establish the setting 
and the flow of action and pinpoints the 
positions of "actors" as well as the van- 
tage point of the viewer. D uring game 
development, the storyboard is used to 
plan in detail the cinematic sequences 
used for game intros and cut scenes. Sto- 



ryboarding is also useful in mapping out 
gameplay routines, such as character 
movement cycles. The information cap- 
tured on the storyboard then serves as a 
visual shorthand for the artists who must 
bring theanimation to completion. 

Though indispensable as a tool for 
collaboration, the storyboard is of equal 
importance to the lone artist. Its useful- 
ness is not just to share a visual concept 
but to plan the whole sequence out ahead 
of time. A s I 've noted before, it is tempt- 
ing for the artist to plunge into an anima- 
tion, but planning ahead is crucial to 
achieve the best possible results. Don't 
assume that at some point later in pro- 
duction you'll work out those issues left 
unresolved when you began. Animation 
is not an improvisational art. It's much 
easier to make changes before you begin 
animating. The storyboard is the place 
for that to happen. 

Keep It Simple 

Storyboarding isn't rocket science, but 
some approaches are generally more use- 
ful than others and some fairly well- 
established misconceptions need to be 
avoided. In this column, I am talking 
about the storyboard as a rough tool for 
planning and sharing visual information. 
I'm not concerned with presentation- 
quality storyboards often used to pitch a 
project or sell an idea. W hen called for, 
such presentation storyboards are created 
easily enough by making a prettified copy 
of your working storyboard. It's counter- 
productive, for several reasons, to add 
polish to your sketches prior to this. 

T he first reason is that the story- 
board should be considered a work in 
progress, not a work of art. It holds every 
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aspect of a sequence up for scrutiny before 
investing time and effort in animation. It 
is successful when it elicits change: 
changes represent a problem or weakness 
discovered and fixed at an early stage or a 
good idea replaced with an even better 
one. Since, due to these changes, many 
sl<etches may need to be scrapped and 
reworked, it's best not to have invested 
unnecessary time and effort into making 
them look pretty only to discard them 
later. 

W hich leads to the second reason to 
keep detail to a minimum in storyboard 
sketches: ego. A storyboard that survives 
review without changes probably wasn't 
looked at critically enough. Suggested 
changes are not a personal indictment of 
the artist's talent. T his is hard for artists to 
accept, though, if they have prepared a 
storyboard filled with painstaking draw- 
ings. Better to think of the storyboard as 
visual shorthand and keep detail to a min- 
imum. A lovingly detailed storyboard 
sketch is akin to a beautifully carved orna- 
mental wooden matchstick: it's so pretty 
you can't bear to use it as intended. 

An aside to those working with a 
storyboard artist: you have entered the 



Realm of C reative E ndeavor. W atch 
where you step: there are unexploded egos 
all around. 

The final reason to build the story- 
board from quick sketches is something 
else I've talked about in this space before: 
flow. Anything that slows down the 
process of translating written script to 
visual information threatens to stifle the 
creative flow. W hen storyboarding for 
animation, you are planning something 
that ultimately will move and have a pal- 
pable pace to it. You need to convey that 
dynamism even in the static panels of the 
storyboard. If you get bogged down in the 
details of a single drawing, you lose that 
momentum: the end result is likely to be 
disjointed and unsatisfactory. Keep it sim- 
ple and energetic. 

Another worthwhile observation 
about detail, or lack thereof— it is a good 
practice to excise repetitive information 
from storyboard sketches. To establish 
setting, you will want at some point to 
indicate the background or portray the 
general color scheme. But it is unneces- 
sary to duplicate this information in 
sketch after sketch if it has not changed 
from one to the next. Storyboarding cap- 



tures what is dynamic in the scene: spend 
minimal time and effort on things that 
remain static. 

In keeping with the quick and dis- 
posable nature of storyboard sketches, 
artists probably do not want to use those 
storyboard layout sheets with columns of 
neat preprinted rectangles on each page. 
Avoid these because it makes changes 
more difficult when, for example, there are 
eight sketches on a single piece of paper 
and you need to replace two of them. It 
also makes it near impossible for the artist 
to remain unconcerned about the "quality" 
of the image while drawing, especially 
once there are already a couple of accept- 
able sketches on the page and any slip-up 
threatens the work already done. 

I nstead, use single sheets of small 
paper— numbering them, if necessary, to 
keep them in sequence. Group the sheets 
on a large board afterwards or as you 
work, securing them with tacks or reposi- 
tionable adhesive. W ith single sheets, it is 
easy for the artist to discard a drawing that 
isn't coming out right or to implement a 
different approach to the scene. A Iso, on a 
storyboard made up of single sheets it is a 
simple matter to remove sketches during a 
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Terra Nova: Strike Force Centauri, the new title from Lool(ing Glass Technologies, features numerous cut scenes blending live action video with 
computer graphics sets and actors. By planning these scenes on the storyboard, artists were able to focus design and modeling efforts where they 
were needed and not waste time on areas that would go unseen. The storyboard also proved useful on the set for staging actors around virtual 
props that had not yet been created. Pictures courtesy Looldng Glass Technologies Inc., Cambridge, Mass. Terra Nova, Lx>oking Glass, and the dis- 
tinctive logos are trademark of Looking Glass Technologies. 



meeting to mark areas that need further 
attention. 

The storyboard needs to consist of a 
series of sketches that establish setting 
and action and guide the creative team 
through the task of animating the 
sequence. Each change of viewpoint must 
be shown; each new character that 
appears onscreen must be indicated. 



H owever, you need not dwell on the 
details of characters, which should already 
be worked out on model sheets (for more 
on model sheets, see "A Question of 
C haracter" in the Feb./M ar. issue). 

Of course, it is important to register 
actions as well: movement within the 
scene is one chief reason we require a sto- 
ryboard rather than a single sketch. H ow- 



ever, don't let the flow from sketch to 
sketch slow down excessively by indicat- 
ing actions in great detail. M ore than one 
sketch can certainly be used to express a 
complex action, but not too many more. 
For the purposes of the sequence story- 
board, your aim is to capture the extremes 
of the movement and leave it at that. A 
separate action storyboard can show in 
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detail how a character walks or hops or 
falls down. 

Explanatory text will sometimes be 
unavoidable on the storyboard, but keep 
it to a minimum. T here will be a written 
script of some sort to start with. The 
storyboard is a complement to this, not a 
replacement for it; nor should a story- 
board repeat most of the script. The 
action depicted in the storyboard should 
be self-explanatory. If not, it's probably 
worth reconsidering the depiction you 
have chosen. Text that indicates the 
accompanying dialogue or narration, 
however, can help communicate the 
sequence's pace and is routinely included 
in a separate block below each sketch. 

Consider This 

Even more important than the form the 
storyboard takes or the appearance of its 
individual sketches are the considera- 
tions that go into taking a written script 
and turning it into an animation. The 
storyboard will act as the animators' map 
on thisjourney. T he challenge is not just 
to convey the plot and action described 
in the script, but to settle upon the very 
best way to tell that story visually. 

In laying out the storyboard, one is 
dealing with the foundations of good 
visual storytelling. Great modeling, ren- 
dering, and fluid animated movement 
can seem strangely hollow if the story is 
not told with verve and style. The 
groundwork for these elements is your 
storyboard layout. Your task may be to 
simply make a splash sequence for a 
fighting robot game: the script calls for 
the robots to stomp around, fly through 
the air, and shoot rockets at each other, 
and then the title pops up. Simple 
enough, on the surface. But how can you 
make that compelling? 

You want to transport your audi- 
ence, cast a spell over them, and even for 
a few moments take them somewhere 
beyond their computer screen— make 
them believe and care about what they 
see on that screen. You don't have to add 
to the plot or action beyond what is pre- 
sented in the script, but you should chal- 
lenge yourself to make the most of the 
material. M aybe you show the action 
from inside the cockpit of one of the 



giant robots, or from down at ground 
level to emphasize their great size, or 
distorted by a wide-angle lens, or with a 
series of quick takes from all these angles 
and more. 

H ow you tell the story affects how 
the audience perceives and responds to 
it. W hat is shown, what is only implied, 
what angles you use, what actions or 
moments are emphasized— these deci- 
sions contribute to the overall impact of 



the sequence. A Iways be wary of the easy 
way out: avoid the obvious, hold cliche at 
bay. W hether the aim of the sequence is 
to amuse, frighten, or thrill, look for 
opportunities to show the audience 
something different and unexpected. 
The storyboard phase is the opportunity 
to consider all these things, to try out 
different ideas, and to settle on an 
approach before getting down to the 
work of animating. 
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W hen the storyboard is laid out in 
front of you, tal<e a critical look at every- 
thing that makes up the sequence: justify 
the presence of each sketch. Your 
sequence will be composed of a number 
of "shots." Even if it all takes place in 
one room, it is shown first from one 
angle, then another; this action occurs, 
then that. E ach is a shot, and your story- 
board must establish every shot. Do they 
all really need to be there? Is there some- 



thing interesting about every shot in the 
sequence? If not, you either eliminate 
the shot, or you find a way to give it 
more punch. Cut scenes within games 
are by necessity too short to support any 
dead weight. 

W ith all that in mind, it is often 
important to plan an animation with an 
eye toward economy. H ow long will it 
actually take to animate the sequence as 
storyboarded? W hat 3D models will 



need to be created, in what degree of 
detail? What texture maps, back- 
grounds, and special effects are called 
for? The answers depend on how the 
sequence has been laid out in the story- 
board. Practical limitations of budget 
and deadline may mean that the best 
way to tell the story from a creative 
standpoint just isn't realistic from a 
production standpoint. 

The storyboard provides you with 
an opportunity to realize limitations 
ahead of time and plan around them. 
For example, one might frame shots so 
that it's only necessary to model the head 
and shoulders of a character rather than 
the entire body. Position certain figures 
at a distance, or show them in stark sil- 
houette so that less-detailed models can 
be used. Or, as I suggested in my article 
on lighting in the previous issue, use a 
cast shadow gobo to represent a figure 
and thereby avoid actually modeling it at 
all. A carefully considered storyboard 
helps you balance at the earliest possible 
stage the twin demands of what- looks- 
best and what-time- allows. 

Even if there won't be any fancy 
animated cut scenes in your game, the 
storyboard is a valuable tool for mapping 
character movement routines or action 
sequences. You'll find that most consid- 
erations outlined above will still apply. 
M ake the movement dynamic for the 
time being, keep detail to a minimum, 
and above all don't be boring. Even if 
you'rejust animating a running sprite for 
a side-scrolling game, use storyboarding 
to lay out different approaches and find a 
way to make that run look interesting. 

Storyboarding will probably be the 
least exotic tool you use in creating digi- 
tal animation, but it will also prove one 
of the most valuable. I doubt any artist 
who has learned to appreciate the oppor- 
tunities it provides for planning anima- 
tions, for optimizing animations, and for 
sharing visual concepts with a team 
would trade storyboarding for all the 
special effects plug-ins ever made. ■ 



D ave Sieks is a contributing editor to 
G ame D eveloper. You can CDntact him at 
gdmag@mfi.ODm. 
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